Agile Documentation: Fact or Fiction?

Documentation in an Agile environment is an interesting topic. The Agile Manifesto places more value on working software than on comprehensive documentation, and 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 when we use an Agile framework? Not at all. I use these three key practices to create effective Agile documentation.

Minimize Artifacts

First, minimize documentation to just what’s needed to get the job done. While software solutions 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 unneeded documents expends valuable time and is counter to delivering the highest value first. Documentation effort should be treated like a requirement if it’s not part of your Definition of Done; it should be estimated and prioritized along with other work. This means weighing the cost of documentation against the anticipated benefit.

Simplify Efforts

Second, simplify document creation effort. My philosophy for simple documentation is 1) do only what’s needed, 2) do it quickly, 3) do it as simply as possible to serve its purpose, then 4) move on. For example, instead of spending hours perfecting a Visio document so everything lines up, the colors don’t clash and the fonts are cool looking, take five minutes to hand-draw the diagram on paper, scan it and store it where the team can access it. 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.

Document Later

Third, create the artifact at the proper time. Just as “big-requirements-up-front” (a waterfall practice) is usually less effective, so is documenting concepts or solutions too early. It often makes more sense to wait until features become somewhat stable before you document them. Documenting later typically reduces rework caused by changes that inevitably occur. However, if documentation is put off too long, you run the risk of undocumented software if resources are constrained or reassigned before documentation is completed. Many agilists prefer building time into each user story for the necessary documentation. In these cases, the “Definition of Done” should specify what adequate documentation means.

The bottom line for effective Agile documentation is to create a document only if it fulfills a useful purpose, keep it simple, and do it when it makes the most sense to reduce rework.