Documentation in Agile, how should it be handled?
Hi Everyone,
I am trying to understand how important is documentation in Agile. As per the manifesto, Working Software over Comprehensive Documentation is favored and I was wondering if there is a measure to understand what is considered too little or too much documentation. In Agile, does documentation normally happen at the start, ongoing or towards the end when the product is stable?
Also, where should these documents be stored? These days many of us use JIRA or similar tools, does our documentation also have to be linked to the user stories we create or should it be some other place? Even if we use JIRA, I believe we are maintaining transparency. In short are there any best practices for documentation and maintaining document transparency?
Does the documentation have to be part of our backlog?
Lastly, is there any official reference that elaborates the 4 values and the 12 principles?
Steve,
It's important to understand that Agile is not a noun, nor a methodology, nor a framework. You can be agile, but you can't do Agile.
The manifesto for agile software development (commonly called the agile manifesto) is a short collection of values, and is based on twelve principles.
Indeed, according to the manifesto:
Individuals and interactions over processes and tools
I believe it was a conscious decision to place this line first. Being prescriptive about using Jira or how much documentation everyone should write would impede agility.
Two of the principles, in particular, may help you find the answer about how much documentation is appropriate in your team / organization:
Simplicity--the art of maximizing the amount of work not done--is essential.
At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.
If documentation is not needed, don't write it. In fact, be prepared to remove it as it gets out of date, if it's no longer useful.
The team should regularly inspect and adapt (amongst many other things) whether it is writing too much or too little documentation, and whether it is achieving the intended results.
In a Scrum context, decisions to adjust the amount, style, location and audience of documentation could be made during the Sprint Retrospective (although it's possible to Inspect & Adapt at any point during a Sprint).
One useful device for ensuring the required amount of documentation is produced along with every releasable Increment could be the definition of "Done".
I am going to steal @Simon's response to give to my own development teams!!!!
One thing I will add. How much documentation is needed? As much as you need. It is pretty simple. Document what you need to in order to be able to use it. What is the purpose of the documentation you are creating and how much will the individuals consuming it need? Where do you store it? Again, who needs it, why do they need it and where do they have access to it?
Remember that documentation can be done in a lot of ways. If you are documenting code you might consider doing it via comments. That puts the info directly in reference to what it is documenting. Are you documenting decisions made while building? Jira tickets might be the place. Do what makes sense.
1.) Include whatever Development Team think is required as part of documentation in the Definition of Done.
2.) Inspect it during the Sprint Retrospective and modify as needed.
3.) Update it in the Definition of Done so that it is taken care in the next Sprint.
4.) Repeat step#1 to 3.
Is there any official reference that elaborates the 4 values and the 12 principles?
I've had to learn the hard way to apply YAGNI (You ain't gonna need it) to not only software but to documentation as well. For us the trick is to document the conversation part of the three Cs in the discussion section of our software (we're using TFS). We have a story, we have the acceptance criteria and the rest of the documentation is in the discussion (or if it's gathered up front, in the description.)
This beats the daylights out of writing long BRDs that nobody bothers to read.
If there's user or system documentation to be written, that's a different animal, but should probably be it's own epic.
As a user I need documentation so that I know how to use the software.
Is there any official reference that elaborates the 4 values and the 12 principles?
The Agile Manifesto and Scrum Guide. Since neither agile and scrum are wholly descriptive on purpose, I don't think you will find a single source from an expert that elaborates. You will find a lot of places where individuals interpret them in their own way. But whether you agree with their interpretation is up to you.
My opinion is that you don't want someone to elaborate. Instead you need to find out how to understand them based on your past and current situations. Understand how they have and do apply to what you are doing. Then as you learn more constantly re-evaluate their meaning.