Essential, Valuable, Timely Documentation

Balancing the Act of Documentation in Agile

20 December 2013

Ashish Sharma
Cognizant Technologies Solutions


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, valuable, and timely.

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

Valuable: 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."

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

Article Rating

Current rating: 3.8 (5 ratings)

Comments

Makarand Purohit, CSP,CSM, 12/20/2013 2:46:45 AM
Very well written and I must say that this post covers only the essential and valuable information. And is timely in reminding that Agile doesn't mean NO documentation. This is in line with the lean practice of keeping everything within a single A3 sheet of paper. If it doesn't fit, condense it to an A4 sheet!
Ashish Sharma, CSP,CSM,CSPO, 12/20/2013 3:02:12 AM
Thanks Makarand for liking the post. Keeping size limited to A3/A4 may sound a good guidance reference to start with but again you should ask if the content of the documentation is really needed (essential) and are the people going to really read it (valuable) and after answering these two questions, even if the size goes beyond A3/A4 - I think it's worth it!!
Karthik Neelakantan, CSM, 12/20/2013 2:17:05 PM
A good summary on agile documentation. One of the most important thing about documentation is that it is a token to initiate the discussion.
Ashish Sharma, CSP,CSM,CSPO, 12/20/2013 11:04:38 PM
Thanks Karthik. Your point looks valid but I have a different opinion. User stories definitely fits as token or placeholder for later conversation but same is not true about documentation. Rather documentation is done when there is no or little hope of having discussion. In cases when you can discuss things, documentation is a waste. Hope this make sense!!
Nirmaljeet Malhotra, CSP,CSM,CSPO, 12/23/2013 2:46:25 PM
Very good article Ashish. While all of what you say makes sense, things get a little different when it comes to financial systems where compliance is sometimes more critical than working systems and the amount of documentation SOX demands. I am presently working on how this can be handled and will be sharing my thoughts soon. You can for sure share you thoughts on the same.
Ashish Sharma, CSP,CSM,CSPO, 12/24/2013 5:29:28 AM
Thanks Nirmaljeet for liking the post. I do not have specific experience with SOX documentation needs and will look forward to hear from you about your experience.
Navdeep Jain, CSM, 4/14/2014 11:46:52 AM
Nice article Ashish. The way you have provided the 3 essentials of documentation gives complete essence of how the documentation should be targeted. Most of the time people take it for granted that being in Agile we are okay with no documentation and in extreme cases were client or management has still not convinced with Agile insist on documentation as full blown even though it might not serve the purpose.

You must Login or Signup to comment.