Agile Documentation

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.

Get Certified

Explore what Scrum is and how to make it work for you in our Scrum Certification training. Hands-on learning will guide you to improve teamwork, deliver quick feedback, and achieve better products and results.

About this course

Focuses on the role of the team and the ScrumMaster. Get the skills and practical experience necessary to improve teamwork, take the exam, and advance your career with a certification that is in high demand today. Often the best fit for anyone new to Scrum.

Learning and Benefits

Relatable Scenarios

Learn on-the-job applications of key Scrum concepts, skills, principles, along with practical solutions that you can apply the next day for difficult, real-life situations.

Respected Certification

Everything you need to earn your Scrum Alliance® ScrumMaster certification, including exam fee and membership, and so much more.

Practical Exercises

With focus on the challenges that real teams face, and tools to dig deeper. You don’t need more boring Scrum theory. You need something you can sink your teeth into to see immediate results.

Jargon-Free Learning

This workshop is not just for software development or people with a computer science degree. We’ve helped many non-software teams with Scrum.

Career Advancement

Use Scrum knowledge to standout at work, get paid more, and impress your customer, all without burning out.

Ongoing Support

Our active Scrum community forum is a safe place to ask questions. Long after you earn the Certified Scrum Master certification, you will have access to the forum, course materials, and additional valuable resources.