Documentation in an Agile environment has been a highly debated topic. It seems the Agile Manifesto places more value on working software than on comprehensive documentation. In fact, one of the Agile principles states, “Simplicity – the art of maximizing the amount of work not done – is essential”. But does this mean we shouldn’t write documentation in Agile? Not at all. I believe there are three key practices to effective Agile documentation.
1. Minimize Artifacts
The first practice is to minimize documentation to just what’s needed to get the job done. While solutions such as software must be maintained and need supporting documentation (either as commented code or external documentation), there is a tendency to create documents simply because “we’ve always written them”, whether they are ever read or not. Creating those documents expends valuable sprint hours and is counter to delivering the highest value first. Documentation effort should be treated like a requirement; it should be estimated and prioritized along with other work. This means weighing the cost of documentation against the anticipated benefit.
2. Simplify Efforts
The second practice to effective Agile documentation is to simplify the document creation effort. My philosophy for documentation is 1) do only what’s needed, 2) do it quickly, 3) do it as simply as possible to serve its purpose, and 4) move on. For example, instead of spending two hours making everything line up perfectly in Visio, take five minutes to hand-draw the diagram on paper and scan it if it needs to be distributed. Also, keep documentation as succinct as possible while still conveying the needed information. Draft it, review it, get rid of the fluff and finish it.
3. Document Later
The third practice is to create the artifact at the proper time during the sprint. Just as “big-requirements-up-front” (a waterfall practice) was proven to be less effective in most software development, so is documenting concepts or strategies too early, instead of waiting to document more stable features. Documenting later typically reduces the effort caused by changes that inevitably occur. However, if documentation is put off until the end of the project, you run the risk of undocumented software if resources are constrained or reassigned before documentation is completed. Many agilists prefer building time into each sprint for the necessary documentation. In these cases, the “Definition of Done” should specify what adequate documentation means.
So, in the spirit of effective Agile documentation, the bottom line is to document only if it fulfills a purpose, keep it simple, and do it when it makes the most sense. We’re always interested in what others think about Agile. Let me know your thoughts on this topic.