Agile Documentation – Just Shoot Me Now
The year was 2007. A longtime friend of mine called and said she wanted to do lunch. She had some “exciting news”. At lunch, she sat down and immediately let me know that her company had finally decided to “go Agile”. My response: “Great! What do you think that means?” She contemplated my open question for 20 seconds before excitedly answering “I’m not sure, but I think it means we no longer have to write any documentation!”
Fast forward to today. A Project Manager is standing in front of her development team explaining the Agile Manifesto. “We value working software over comprehensive documentation”. She then emphasizes that Agile is no excuse to ignore documentation, and as a matter of fact, it is best to document everything! When new team members join, they must have full documentation on everything to help them get up to speed. We need written records capturing all decisions, explaining why something is the way it is.
Just shoot me now.
A Healthier View
These two real scenarios demonstrate different extremes of documentation in Agile. Both are unhealthy. In the first scenario, there is zero documentation. In the second scenario, there is documentation for everything.
I am often asked “In Agile, how much documentation do we write?” I typically answer something like “You should document only when the team believes there is strong value in spending the time documenting instead of coding and testing”.
A healthier view of Agile documentation (caveat – based on my experience) is to begin by developing lightweight user stories to capture the essence of the requirements. Yes, this is documentation! Acceptance criteria, in effect, describes a rough view of the functionality. Attachments to the user stories can show ancillary information such as UX design and schemas. Follow that with documenting key design ideas pictorially using a PowerPoint slide or two when it helps. Complex algorithm? Write a brief Word document summarizing how it works from a layman’s perspective. APIs? Document these as a vehicle for discussion around content and payload structures.
It sounds like a lot, but in reality, it is a minimalistic approach to documentation. None of the above are truly required for every situation, but if these lightweight documents are considered valuable by the team, then write a product backlog item to capture each effort. Prioritize them accordingly amongst all other user stories delivering business value.
Flash Back
In scenario 1 above, the planned 1-hour lunch turned into a 4-hour discussion with my friend on what “going Agile” really means. It was not a celebration of no longer having to write documents. I was able to explain that documentation is still important in Agile, but we use it judiciously and in a very targeted high-value situation. And yes, I paid for lunch.
In scenario 2 above, I am seeing small bits of progress by the Project Manager as I try my best to influence her to rely on means other than comprehensive documentation – for example, tacit knowledge, team-based mentoring, essence-based approaches, and when all else fails go to the source code to see what the real design is.
Visit here for another good overview of documentation in an Agile world.
Visit here for a concise view of what all is involved in an Agile transformation.