Agile Documentation in Software Development

Technical Writing at Adcubum

Adcubum is the Swiss number 1 in terms of health and accident insurance. Established in 1997 by five students from The University of St. Gallen, Adcubum now has 8 offices and over 400 employees, and a solid position as a software developer for insurance companies. 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.

It is easy to see that, from the technical writer’s viewpoint, being closely embedded in these 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. They are also separate from the role of 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. This is because, in addition to the specific project tasks, technical writers also have to agree on cross-team standards. To do this, the technical writers 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.

Working in Sprints

The work of the development team is organized into sprints – short blocks of work lasting one to four weeks. During sprints, requirements are recorded, evaluated, and the associated time needed is estimated. These requirements are also implemented, after which customer feedback is obtained. From the knowledge gained from this feedback and the experience gained in the sprint, further knowledge then flows into the next sprint. Since sprints only organize parts of the development process, 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 also part of the product, so the results of their work are included in the customer review along with the programmed components of the software.

Agile Authoring – Is it Worth it?

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. As technical writers, they can more easily influence the development process; undesirable developments are easier to avoid. The method of working in a scrum process is also extremely helpful. It allows documentation to be completed gradually, rather than as a large whole at the end of the development process. On the other hand, 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.