Agile documentation – how development and technical writing complement each other

Agile development has, in recent years, established itself as a method for controlling software projects. At its heart is the conviction that the development of software components should no longer be meticulously planned from start to finish. Instead, the developers rely on a set of repeatable and manageable “sprints” that culminate in a series of tests. The interim “result” is then evaluated and, in the ideal case, supplemented with feedback from the customer. Only then is the next sprint started. The aim here is to be able to adjust the arc of a project when the requirements change or it transpires that the desired solution is no longer achievable in the form originally planned.

Various methods exist to support agile working: Kanban, Extreme Programming or Scrum. The Scrum approach has apparently emerged as the most popular method in recent years. There are four main roles in a Scrum development team. The responsibility of the “Product Owner” is to ensure that the final product is realised in a way that reflects the project’s objectives. To this end, he or she must also obtain continuous feedback from the “Customer” or end user (the second role). This is important, as the requirements arising from the original vision for the product often only become apparent during the development project. The “Scrum Master” (role number three) looks after the internal organisation of the project team, eliminates any obstacles to the project and facilitates its smooth operation. The fourth role within a Scrum project is the project team. This team will hopefully bring together many differing skills and, in addition to the developers, also include interface specialists, testers, 2nd level support or UX designers.

Technical writers are therefore typically to be found within the project team. In addition, they can also make exceptionally good product owners, as they will be well versed in seeing products from the user’s perspective. However, there are recurring discussions (among developers) as to whether technical writers have any sort of role to play during the development process. This stems from one of the requirements of the Agile Manifesto, which demands the following of internal documentation: “Working software over comprehensive documentation.”

What this is understood to mean is that the software should theoretically be able to be used without any documentation. In practice, however, it has been shown that software above a certain level of complexity relies on documentation if users are to be able to make use of its full functionality.

It is therefore good policy to ensure that technical writers are tightly integrated into the Scrum teams, even if this can sometimes create an organisational problem. Frequently, writers will not just be working on a single program component, but may be involved in a whole range of applications. They therefore have to be embedded in a number of Scrum teams at the same time, which can occasionally cause conflicts with regard to deadlines and resources. If, however, it’s generally accepted that technical writers have an important role to play, then such conflicts can be resolved (if necessary, with the help of the Scrum Master).

Everybody wins, as the Scrum teams gain some valuable know-how. And that’s not just because technical writers usually have a better idea of how users operate than developers. As the focus of their work is on writing, they guarantee that terminology is developed and applied consistently, e.g. for the GUI strings. In the final analysis, they help ensure that the localisation of the software proceeds more smoothly by providing a standardised and user-friendly interface.

On the other side of the fence, working as part of the Scrum team gives technical writers greater scope. They see at first hand the direction the development of the software is taking and can adapt their writing processes accordingly. In a conventional development process, the technical writers are often not involved until the development is complete, by which time they have practically no way of influencing its outcome. Working in an agile team makes it easier for them to flag up their requirements and raise any concerns early on should it become apparent that decisions taken during the software design process are going to generate more documentation.

To this end, the documentation has to be seen as an integral part of the product. This is best achieved by including the documentation as part of the “Definition of Done” (the criteria that determine whether a sprint is complete). A minimum requirement in this respect is that documentation is at least mentioned. It is better practice, however, for individual aspects of the documentation to appear as specific points in the Definition of Done, e.g. “GUI strings use standardised texts.”

After all, if this tight integration within the Scrum teams is a success, then there will be no conflict between “agile” and “documented” – since the end result will simply be “looking good”.