Saturday, June 15, 2013

Right-sizing Documentation in an Agile World

Within an Agile context, there is a focus on right-sizing documentation.  This is a response to the bureaucracy that has led to large volumes of project and product documents which are often left unread, are out-of-date the moment they are complete, and seem to have little value to the team.   On the other hand, I have heard folks who are in an Agile context say that no documentation is needed.  The truth is somewhere in between.    
One of the values in Agile is “working software over comprehensive documentation”.  This does not mean that there is no value to the item on the right, but there is more value to the item on the left.  The key is right-sizing the documentation.  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).   With that in mind, here is some high-level guidance on right-sizing documentation. 
  • Documentation should be living and evolutionary and not “sitting on the shelf”.   Move away from the notion that document is “final”.
  • Consider some documentation to live at the product level where it may naturally evolve from both sprint to sprint and from release to release. 
  • 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   
  • Update your documentation continuously as new things are learned.  If you learn something that can impact the team or help with decision-making, go to the document and update it. 
  • 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.  If you no longer need the document, it is reasonable to retire it. 
  • Be concise.  Write in succinct prose and add bullet points if reasonable.  Avoid long and flowing prose which may lose the reader’s attention.
  • 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
  • Document decisions.  Knowing the decisions helps those who must maintain the product and understand why things were decided or done in a certain way.   
  • Realize that there is a difference between internal documentation and external documentation.  External document may be a User Guide or any document that gets delivered to the customer.  These should be considered as “working software” and follow the rules of the done criteria.    

What do you think of this guidance?  Do they make sense?  Do you have any other tips?