Document Continuously: An Agile Core Practice

If your goal is to have potentially shippable software every sprint as they say in Scrum, or better yet to have a potentially consumable solution every iteration as they say in Disciplined Agile (DA), then you will need to keep your deliverable documentation in sync with your software/solution – in other words, write deliverable documentation continuously throughout your initiative. This strategy is overviewed in Figure 1.

Figure 1. Documentation through the SDLC – Document Continuously Strategy (click to enlarge).

Deliverable Documentation on Agile Teams

I’ve been using the term “deliverable documentation”, but what does that mean? Deliverable documentation is the documentation that you need to deliver to your stakeholders as part of your overall solution. This will of course vary between teams, but deliverable documentation typically includes user manuals, training materials, operations manuals, support manuals, and system overviews. It typically does not include requirements specifications or design specifications, except of course in regulatory situations where such documentation is required or in contract negotiations where it’s required as part of the contract. Of course, with all such artifacts, I highly suggest following the core practices of agile documentation.

Document Continuously in Practice

Here are some good heuristics to document continuously in an effective manner:

Wait for the information to stabilize. Write the documentation after you’ve done the majority of the development work, in other words towards the end of the iteration. If you document information that isn’t yet stable, you run the risk of having to rework your documentation.
Write documentation during the iteration with long iterations. With “long” iterations, say four weeks or more, you have sufficient time for information to stabilize and thereby capture it during that iteration.
Write documentation the following iteration with short iterations. With “short” iterations, two weeks or less, it’s unlikely that the information will stabilize in time for you to complete the documentation. To remain efficient as possible you should consider writing the deliverable documentation for iteration N during iteration N+1. With medium length iterations (two to four weeks) you will need to experiment to identify which approach works better for you.

Note that with this practice many teams will include criteria around updating deliverable documentation in their definition of done for the iteration. In other words, documentation becomes part of the acceptance criteria for determining whether a work item (such as a user story or defect report) has been fully implemented. This reflects the Disciplined Agile (DA) philosophy of solutions over software.

Shouldn’t My Team Wait Until the End to Write Documentation?

Rather than keeping your deliverable documentation up to date throughout your initiative, your other option is to leave the finalization of it to the end, to document late. With this approach you reduce the documentation effort because you do not need to evolve it as your other work evolves, but you run the risk that you will not be given sufficient time to write it.

Document Continuously in Context

By writing deliverable documentation continuously throughout the initiative, you address the following risks:

Delivery risk. By writing the documentation in sync with the rest of the solution, you know you have sufficient documentation to support what you’ve built to date. The implication is that your solution will in fact be potentially shippable at the end of each iteration.
Accuracy risk. Because the feedback cycle between doing the work and documenting what you did is short it is much more likely that you will remember the critical details which need to be captured.

However, there are three risks which are potentially increased by this practice:

Financial risk. Because the requirements are likely to evolve throughout the initiative, you will need to update the deliverable documentation to reflect those changes. You are in effect “travelling heavy” from an agile point of view by documenting continuously.
Schedule risk. It takes time and effort to write and maintain this documentation, and any rework of the documentation resulting from evolving requirements in effect impacts your schedule due to the required rework.
Accuracy risk. Sadly, it’s easier to write about documenting continuously than it is to do it. It’s common that agile teams will put off writing documentation until they have time to do so, in effect moving towards the document late practice instead of this one.