Software Documentation: Agile for the Win

Speed is paramount in software development – the goal is to get a product that is valuable to the customer onto the market as quickly as possible. But once a solution has been launched, the job still isn’t finished. New features are continually added to the product, and security updates are a must. In other words, software is basically never finished, unlike a machine that has been delivered.

The requirements placed on software and the digital world continue to evolve, and the digital product therefore changes along with them. By using agile methods, developers can stay on top of all this. They catalog new requirements, rewrite them as stories, and prioritize them. Then, they work in sprints and as part of a team of testers and agile writers to build the best solution for the given requirement.

Expert software in particular leads to a huge need for information on the part of users, such as IT administrators and end users. Sometimes, users have to start by learning concepts and procedures before they can work confidently and efficiently with a software solution. So it’s no surprise that they have a never-ending need for good software documentation in the form of manuals, online help, tutorials, e-learning courses, and so on. Looking to the future, this need will only continue to grow in the field of software as the world of work becomes increasingly digitalized.

Software documentation covers a wide range of topics and target groups – this is one of its typical characteristics. For example, let’s say an IT company offers a software solution for controlling production processes. What target groups does the documentation need to address with its content?

First, there are the people who use the software. But in the case of our example they use the software to not only control processes but also plan the process logic, so we have two different user groups: plant operators and project planners.

Then there are the software administrators. And because this software can be programmed via an API, we also have a fourth group consisting of software developers. In addition to conventional IT documentation for programming purposes, both of these target groups also need code that is clearly commented out so important functions, methods, and parameters can be found directly in the source text.

Each of these target groups uses the software to complete different tasks, so they each have their own information needs that have to be taken into account in the technical documentation.

The target groups are diverse, but there are also other challenges that need to be dealt with:

• Content of the documentation: One aspect that makes a big difference in terms of the documentation is whether only one version of a software product needs to be documented, or several versions at the same time. A further degree of complexity arises when the software can be custom configured and the technical writing team doesn’t know which specific package the users will be working with when creating the documentation. And, of course, translation requirements are also a key factor.
• Authoring process: In many companies today, software engineering means agile methods. This is definitely a good choice on the part of software development, but it’s essential that IT documentation requirements are also systematically addressed in the agile process design. This is the only way to ensure that the documentation will be available to the customer at roughly the same time as the software.
• Changes in user expectations: Providing information in digital form is the current standard, especially for software users in the professional environment. They want a quick and easy way of finding detailed information for specific problems. Document-only approaches that “hide” these details away in PDF manuals with hundreds of pages don’t live up to their requirements. This need for concentrated, ready-to-use knowledge is also reflected in the growing popularity of instructional videos. Which makes it no surprise that the field of technical communication is responding, and more and more software providers are using videos to share concepts and simple processes.

How can software companies best tackle these requirements on their documentation? The key is to look at your current situation and then take a targeted approach to developing the documentation – rather than just jumping in anywhere. If you’re facing this same challenge, you’ll want to consider the following three aspects in your improvement strategy:

Which information media and channels does your technical writing team want to offer your customers? And what content do you want to or have to communicate there? Going back to our example, the software company’s media concept might look like this:

PDFs are only used for content that needs to be made available in printed form due to legal reasons. The main source of information for the plant operator and software developer target group is a modern, browser-based help tool in HTML5 format that explains simple processes using step-by-step instructions. As well as the usual text and image content, videos can also be shown in the browser-based help tool. Thanks to a modular structure and coherent indexing, users can zero in on the specific content they need.

In addition to the help function, there is a web-based knowledge base that users can access via their browser. The knowledge base is optimized to provide answers to individual questions and consists partly of help content, but also assistance available from the support team.

All of the media can be updated automatically, with the exception of the PDF files. This ensures that the main sources of information (in our example the HTML5 help and knowledge base) are always up to date.

Who creates what information in the company? How do IT specialists in development and the technical writing team link up their work to produce effective results? What standards apply to text, graphics, and moving images? How does information need to be indexed?

All of these questions form part of the authoring process. The more channels you have defined in your media concept, the more important it is that the work processes run smoothly.

A modern content management system is an indispensable tool in this process. By centering your organization around a component content management system (CCMS), you not only have a flexible way of providing content for the required channels from a single data source (learn more about single source of publishing), but you can also involve various collaborators in the authoring process – from technical writers, to project managers and subject experts (e.g. developers), through to those responsible for the review process.

What does an agile approach look like in practice when technical writers and the development team work together? Sven Schmitt, a technical writer at Quanos customer Adcubum, shares his insights. The company is the Swiss number 1 in terms of manufacturing software for health and accident insurance. Established in 1997 by five students from the University of St. Gallen, the company has since grown to become a sizable enterprise with eight offices and over 400 employees. Adcubum is a winner of the European Xcelent Award for Customer Satisfaction. Agile development processes that allow customer requirements to be implemented speedily and precisely are an important cornerstone of this success.

From Sven Schmitt’s viewpoint, being closely embedded in the development processes and thus in the development team is a decisive factor. Technical writers play a special role in an agile team, and are responsible for documenting the development progress and compliance with terminology. This clearly isolates technical writers from the developers, from the scrum master as team facilitator and support, and from Quality Assurance.

Although product owners are also outside the development team, they play an important role because they define and prioritize requirements. This applies to the quality of the documentation too, so product owners always need to keep an eye on the technical writing as well.

The cross-sectional tasks of the technical writers are also organized outside the development team. In addition to the specific project tasks, technical writers also have to agree on cross-team standards. To do this, they get together in “guilds” headed by a documentation lead. Overarching documentation topics that are important for all technical writers, regardless of their affiliation to a given team, are discussed at bi-weekly guild events.

The work of the development team is organized into sprints – short blocks of work lasting one to four weeks. During these sprints, requirements are recorded, evaluated, and implemented, after which customer feedback is obtained. This feedback and the experiences gained in the sprint then flow into the next sprint. Sprints only cover parts of the development process, so they continue to follow one after the other until the product is ready to deliver.

In every phase of the sprint, a technical writer must identify, work on, and check documentation-related tasks. With their knowledge of terminology and how to communicate content they perform an important advisory function within the development team. The documentation is part of the product, so the results of their work are included in the customer review along with the programmed components of the software.

So how does the balance sheet look for the technical writing aspect in such an environment? Sven Schmitt regards the close integration into the development process as a positive thing. Information flows more easily and feedback from the development team and the customer reaches the technical writer faster. And the technical writer can more easily influence the development process, which makes it easier to avoid mistakes. Sven also sees the method of working in a scrum process as extremely helpful, because it allows documentation to be completed gradually, rather than as a large whole at the end of the development process. The needs of the documentation are always kept in view since this is an integral component (and thus an integral requirement) of the development process.

The close embedding in the development team also has its disadvantages. It makes compliance with text and terminology standards much harder across the various teams. The documentation cannot always be completed in parallel with the development, or there may be unnecessary retrospective changes to the text. The acceleration of releases and the multiplication of software versions also make the work of the technical writer harder.

But all things considered, it’s clear that technical writers can work well in agile processes if they have a solid role within the development team and their needs are heard in the sprints.