What does Agile say about documentation?

“Working software over comprehensive documentation…

…That is, while there is value in the item on the right, we value the item on the left more.” (Agile Manifesto) These are not the words that an IT project auditor wants to hear; surely we need big documents describing every last detail of the software we are building? Hazzan and Dubinsky describe three implications of this principle in their book Agile Software Engineering[1st of 5 paragraphs]

Firstly, what are valuable documents for the team, their stakeholders and the process of building the software? A photo of a wipeboard with the latest user stories for the current sprint could be an essential record. Increased documentation volume doesn’t mean increased product quality but the right documents completed correctly and used by the right people can certainly make a difference. [2/5]

Secondly, Agile gets development going quickly, the focus is on building, not documenting. It’s still important to make a record of what is being built but the iterative nature of Agile implies living documents that are continuously updated to reflect the cyclical improvements to the software. This principle is not an excuse for laziness but rather an affirmation of efficiency and just-in-time. [3/5]

Thirdly, customers appreciate engaging with working software and interactive demos much more than sterile, lengthy documents. Customer engagement will be far better when they can touch and feel what they getting rather than trying to visualise it from a written source. People want to see what’s “in the box” rather than read about it “on the box.” [4/5]

A skilled project auditor will understand these concepts and know how to interrogate the written record so they add value, not just tick boxes. Also don’t confuse quality with quantity and produce documents just to show progress. Mark Twain must have been thinking about Agile when he wrote, “I didn’t have time to write a short letter, so I wrote a long one instead.” [5/5]

View this article on LinkedIn

Leave a Comment

Your email address will not be published. Required fields are marked *

Sign up to our newsletter!

Scroll to Top