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
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
- 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
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
- 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.