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 we say in Disciplined Agile Delivery (DAD), then you will need to keep your deliverable documentation in sync with your software/solution -- in other words, write deliverable documentation continuously throughout the project. This strategy is overviewed in Figure 1. Your other option is to leave the finalization of your deliverable documentation to the end of the project, to document late.

Figure 1. Documentation through the SDLC - Document Continuously Strategy.

Agile Documentation - Document Continuously strategy

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 projects, 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 best practices of agile documentation.

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

  1. 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.
  2. 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.
  3. 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.

Risk Profile of this Practice

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

  1. 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.
  2. 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:

  1. Financial risk. Because the requirements are likely to evolve throughout the project, 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.
  2. 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.
  3. 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.
Agile Documentation