Agile Documentation Zeitgeist

“Truth can only be found in one place: the code.” - Robert C. Martin

Documentation is unarguably expensive. What about its value? That’s highly questionable. From an Agile perspective, the question of value is ever present, particularly when the topic is documentation.

However, Agile does require some level of formalisation and it is irresponsible to start a project without a backlog, a proper release plan or strategies on how to communicate and report progress.

The aim of this very << document >> is to singlehandedly save your organisation millions of dollars by avoiding creating documents that are instantaneously superseded, impossible to find in Sharepoint, hard to maintain and that no one ever reads. To achieve this I’ll employ a single, key Agile concept from the Manifesto: working software over comprehensive documentation. 

Keep these in mind when deciding whether to spend time and money writing a document:

• WRITE if the reader (person, not process) is clearly identified.
• WRITE if you can sit down (feedback via email doesn’t count) with the reader and confirm that the document delivers the expected value.
• DON’T WRITE when it’s a palliative measure to poor work, e.g. commenting code because no one understands it. Instead of writing the comment use the time to make the code self-explanatory instead.
• DON’T WRITE documents to use them as a shields in the future, work on building trust instead.
• DON’T WRITE documents that people have to be trained on to use.
• THINK hard about it if the word “Detailed” is part of the document’s title. The only time something can be truly detailed is at the end. Big upfront design documents are a no-no.
• TRACK how much effort is spent on producing documents using story cards in the same way you would with every other piece of work (on the wall and with estimates).

Finally, if you are a lead of sorts, PM, IM, etc. let the team create whatever makes sense for them and focus exclusively on documents that must be produced to communicate with other teams.