Including documentation in an agile software development process

Documentation is time-consuming

I recently went to a software development conference. There I heard people complaining about how time-consuming requirements engineering or even documentation is.

The people I talked to often referred to the agile manifesto – working software over comprehensive documentation – as an excuse for not writing documentation and only focusing on working software.

It has to be mentioned that even though the left side of the manifesto plays a greater role than the right side, the right side is not irrelevant. The agile manifesto is used to generate value and the documentation is part of the overall value.

Further in the discussion, they complained about how much time they spend on writing documentation before the release of a milestone. On average, they had two developers who wrote documentation for about two sprints and on top of that, they reserved one sprint for review improvements from their team. This comes down to two people working on documentation on three sprints, which are about six weeks’ worth of time.

Our Best Practice

In our projects (mainly medical software), we have to write a lot of documentation, too. But we choose a different approach and add the documentation effort to our development process. Here is how:

Step one, the documentation needs to be part of the story. If the documentation is part of the story, the definition of ready needs to be updated. A story is first ready to be planned and estimated after it is clear if the documentation needs to be updated.

The next step is to add “writing documentation” to the story estimation. During the sprint planning, we are estimating story points for each story depending on time and complexity. Now we are taking the time it takes to update the documentation into account for the estimation. This ensures that we have enough time to write the documentation during the sprint.

Next, the writing documentation needs to be part of the definition of done. As updating the documentation is part of the definition of ready, the documentation is now part of the definition of done. Here, it´s the responsibility of the reviewer to review not only the code but also the documentation.

Lastly, a step in the CI to generate documentation needs to be added. The same way the code is built, unit-tests are executed, and other automated code analysis tools are validating our code implementation in our CI. By adding this step, anyone can read and review the documentation at any point and the documentation is under version control.

Documentation is part of the project

As the documentation is now part of our development process, everyone in our team is encouraged to read the documentation, add something, or review the documentation, which implies that it is always up to date. The initial goal to minimize the time effort of writing documentation before a milestone release is achieved by spending some time on the documentation with every sprint. Therefore the documentation always aligns with the state of our development.

One last benefit I would like to mention is that we can generate the documentation at any point for any given software version because the documentation is version controlled.

What do you think about this approach? How is documentation handled in your project?