Agile Documentation

One of the principles of the Agile Manifesto is "Working software over comprehensive documentation".

This usually rises the question of how much documentation is the right documentation !?

I posed this question to Mitch Lacey on his interview. You can see his answer here. But today while reading the Agile Database Techniques book I noticed a section about Agile Documentation which I found very interesting.

Here is the summary from that section of the book:

Documentation is an intrinsic part of any system. The creation and maintenance of which is a "necessary Evil". Liek agile models, agile documents are just barely good enough.

A document is agile when it meets the following criteria:

• Agile documents maximize stakeholder investment- The benefit provided by an agile document is greater than the investment in its creation and maintenance.


• Agile documents are "lean and mean" - They contain just enough information to fulfill its purpose, in other words it is as simple as it can possibly be. Bullets form is allowed. Content is more important than representation.


• Agile documents fulfill a purpose- They fulfill a single defined purpose. If you don't know why you are creating the document, or the purpose is questionable, then stop and rethink what you are doing.


• Agile documents describe information that is not likely to change- The greater the chance that information will change the less value there is in investing significant time writing about it.


• Agile documents describe "good things to know"- They capture critical information, information that is not readily obvious.


• Agile documents have a specific customer and facilitate the work efforts of that customer - A document written for maintenance developers is different from user documentation or tutorial. Work closely with the customer for your documentation if you want to create something that will meet their needs.


• Agile documents are sufficiently accurate, consistent and detailed - Agile documents don't need to be perfect, they just need to be good enough.


• Agile documents are sufficiently indexed - Documentation isn't effective if you cannot easily find the information contained in it.

From the book Agile Database Techniques: Effective Strategies for the Agile Software Developer (Wiley Application Development) (Paperback), by Scott Amber