Agile Documentation. Is it an oxymoron? The Agile Manifesto says “Working Software over Comprehensive Documentation”. It doesn’t say no documentation, and it doesn’t say how much, if at all.
In an Agile world, we focus our work on delivering value to the customer, not on chronicling the process. At a high level, some teams maintain a one-page system design document. Other teams have used a whiteboard with a “best before” date and, once the whiteboard expires, someone takes a picture with their phone and wipes it clear. If the erased information is still valuable, several people work together to create a new version of the picture based on their current understanding of the system. The elegance is that it starts fresh and it is created collaboratively.
What about the user stories as documentation? They seem like documents at first. The challenge is that they degrade in value over time. They’re just intended to be a placeholder that starts a conversation among the team members about the piece of the product that they’re building. The problem is that a description that works well as a User Story, isn’t meaningful months after the implementation is complete. We forgot the details and, in many cases, the original user story can no longer be found since the system that has been built on it obscures the original.
The acceptance criteria become low-level documentation. Teams that learn Behaviour Driven Development often use the examples created in that approach as their documentation. Even better, if they have mastered the art of automating their examples, they become executable documentation. Executable examples can be run, and if they pass then both the code and docs are in agreement. If they fail, then either the code or the examples need to be updated.
Instead of looking to add more documentation, seek to reduce the need for documentation. In many cases, it exists solely for the handoff to the next group of people (test, deployment, etc). Instead of creating a document; eliminate the handoff. Agile teams should include testing and, with the advent of DevOps they include people with knowledge of operations, so handoffs are eliminated.
Before agreeing to create new documentation, I prefer to ask team members these questions: “In 6-12 months will you be prepared to spend several hours updating this document?” and “How will you know when this documentation is out of date?”
If you expected a template, effective ones don’t exist. Ultimately the team members need to negotiate amongst themselves with the Product Owner what documents they need, and what the minimum amount is that is required to do the job effectively.
Resources Links:
- Agile Requirements Documentation – What’s Really Needed?
- Best Practices for Agile Documentation
- Four goals of Agile documentation: Part one and Four goals of agile documentation: Part two
- A Roadmap to Agile Documentation
See Also:
Behaviour Driven Development
User Stories
Mark Levison has been helping Scrum teams and organizations with Agile, Scrum and Kanban style approaches since 2001. From certified scrum master training to custom Agile courses, he has helped well over 8,000 individuals, earning him respect and top rated reviews as one of the pioneers within the industry, as well as a raft of certifications from the ScrumAlliance. Mark has been a speaker at various Agile Conferences for more than 20 years, and is a published Scrum author with eBooks as well as articles on InfoQ.com, ScrumAlliance.org an AgileAlliance.org.
*Thank you for visiting the World's Largest Opinionated Agile Reference Library. This content is created and the links are curated through the lens of Agile Pain Relief Consulting's view of what is effective in the practice of Scrum and Agile. We don't accept submissions and emails to that effect are marked as spam. Book listings may use affiliate links that could result in a small commission received by us if you purchase, but they do not affect the price at all. From experience, this won't amount to anything more than a cup of coffee in a year.« Back to Glossary Index