The Manifesto for Agile Software Development values "working software over comprehensive documentation". This core value asks us to think about how much and which kinds of documents are needed and when they need to be written.
In the blog post Minimum Viable Deliverable Jonathan Berger writes about communicating design decisions. He shared his view on using documentation:
The Agile Manifesto prefers “Working software over comprehensive documentation”, so why are designers spending time on artifacts the user will never see? Agile seeks to minimize waste, so taken to its logical extreme, all documentation is waste. That doesn’t mean documentation can (or should) be done away with entirely; it’s necessary for teams to function (particularly at scale). But it does suggest that minimizing documentation is a Good Thing, and that designers ought to be seeking to communicate design decisions with the least amount of work possible.
Jonathan provides suggestions how you can minimize documentation:
1) socialize the idea that “less artifact can be better” among your team
2) always ask the question: what’s the least amount of deliverable that we need right now?
Ashish Sharma wrote about balancing documentation and discussion in Agile essential, valuable, timely documentation:
The goal in Agile should be to find the right balance between documentation and discussion. Documentation is an important part of every system, Agile or otherwise, but comprehensive documentation as such does not ensure project success. In fact, it increases your chance of failure.
He mentioned three criteria that you can use when deciding how much documentation should be written and when to write it:
Essential: Document with just barely good enough detail.
Valuable: Document only when we actually need it, not when we want it.
Timely: Documentation should be done in a just-in-time (JIT) manner, when we need it.
Michael Nygard described a process view to documentation. He suggests to begin with the end in mind:
I often find processes with no consumers. Pure waste! Literally nobody uses the output, but the producer doesn't realize it.
Processes, including their inputs and outputs, could be described from the perspective of the consumer as Michael suggested. He shared a set of questions that you can use to do this:
- Who is the consumer?
- What do they need?
- How do you deliver it to them?
- How do you know when they're ready for it?
- How do you produce it?
- What inputs do you need to produce it?
Tom de Lancey started a discussion early 2013 on LinkedIn about Emergent Documentation: One way that agile is very different from waterfall:
Many people are very uncomfortable letting go of the familiar documentation that they are used to: Systems Requirements, Systems Design, Vision and Scope, use cases, schemas, work-flow diagrams, Rational Unified Process artifacts, etc. Many cannot reconcile boiling all that documentation into a five sentence story.
He described an approach on documentation which he called “Emergent Documentation”:
(…) we do not want to waste time and effort in documenting something that we have not yet discovered how to do. We document as we discover. We document only what we actually DID, as opposed to what we thought we were going to do.
One of the benefits of this emergent documentation approach as described by Tom is that:
Documentation becomes part of the development process, not a separate activity. Since the documentation is actually useful, the whole team has an interest in maintaining it. Each story has a separate task to update the WIKI (a SharePoint web site that connects to each story).
Mario Moreira wrote a blog post about right-sizing documentation in an agile world. Right-sizing as Mario described is a response to the large amounts of documents that software projects had or have:
Right-sizing means that the level of effort applied to write and maintain the documentation plus the value of that written document should have a greater return on investment (ROI), then not having that information readily available (i.e., the effort it would take reconstruct the information and impact of not having that information for current decisions).
His blog post provides guidance on right-sizing documentation. Some of his suggestions are:
- Documentation should take on a collaborative nature. It should not be written by one person to perfection, and then shared with others. It should instead be shared often during draft to gain input.
- Focus on just barely good enough documentation and avoid big upfront details which typically means a lot of guessing and wasted time. Barely good enough means document what you currently know.
- Documentation can take many forms. It is not only a Word document, documentation can live on a wiki, in the Agile planning tool, as comments in code, and much more
How do you do documentation in Agile? How much and when?