One of the core values of the Agile Manifesto is "working software over comprehensive documentation." There are couple of things that are very clear here. First: Contrary to the common myth, Agile does not suggest no
documentation. Second: It advises us to move away from long, detailed documentation and do only as much we are required to do in a timely manner. 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.
However, the question remains: How much documentation is enough, and when should you write it?
To me, the answer lies within three words: essential
, and timely
Document with just barely good enough detail. Each system and environment has its own unique documentation needs, and certainly one size does not fit all. Keep the documentation as concise as possible: overviews, road maps, and high-level architecture diagrams are generally preferred over detailed documentation. Developers rarely trust detailed documentation, because it's usually out of sync with the code. Also, we must remember that requirement documentation is just one form of documentation; we also will have other forms of documentation in projects, such as test plans, test cases, and code itself. With high-quality source code and a test suite to back it up, we will need a lot less system documentation.
Sometimes we need to do the documentation because of contractual obligations or industry regulations (like FDA and SOX), but nowhere does it say that we need to be ineffective and wasteful. With a careful approach, we can surely meet the regulatory obligations with the minimum required documentation that just meets the criteria.
Document only when we actually need it, not when we want it. Agile projects prioritize work in the order of value, so the stakeholders must understand the value and total cost of ownership for a document, along with other requirements, and must explicitly choose to make that investment. Obviously, the benefit of having documentation must be greater than the cost of creating and maintaining it. Mike Cohn
, quoting colleague Tom Poppendieck, suggests, "When documents are mostly to enable handoffs, they are evil. When they capture a record of a conversation that is best not forgotten, they are valuable."
Documentation should be done in a just-in-time (JIT) manner, when we need it. Ideally, we should create documentation throughout the entire software development life cycle when it makes the most sense. We should take an evolutionary approach to its development so that you gain feedback as to its actual value. The best documents are written iteratively, not all at once. The benefit of this approach is that mostly we are ready with documents with just enough detail, just in time, to go along with potential software deliveries.