As the Agile Manifesto stated that it prefers “working software over comprehensive documentation”, some early Agile adopters jumped to the conclusion that documentation was useless. Thus Scrum software developers should only concentrate in creating working software with code that was the most easier to understand. The Agile Manifesto however also said that there is some value on the left side of the comparison and in her tow blog posts Birgitta Böckeler reminds us that Agile documentation fulfills some important goals.
Birgitta Böckeler starts her blog post explaining that there is value in documentation, that there is no fixed rules about how much documentation is enough and finally that documents have different audiences from software developers to final users. Then she follows by listing four goals that documentation can have for Agile and Scrum teams.
1. Creating a shared understanding
Some things might seem to be clear in the heads of the members of the Scrum teams but with a slightly different point of view, like the software architecture for instance. Creating a document helps team members to discuss formally the topic and achieve a common understanding. Birgitta Böckeler proposes to create a wall of shared understanding with the main things that Agile members team should agree upon. She provides some tips on how to select the items that should appear on this wall.
2. Expose complexity
Even if Agile software developers should strive for simplicity, there are often some points that might require more explanation, like a data migration plan for instance. In this case, infographics and paper information widgets are tools that can help you.
3. Create empathy
Being able to refer to some documents to understand how things work can help prevent anxiety for Scrum team members and other stakeholders. Complex algorithms and code that is frequently showing bugs after modifications are good candidates for documentation.
4. Helping future decisions
When the software begins to age and being maintained by other people, having some reference about how it was built and why certain decisions where made can help people to evolve it in a better (and safer) mode. It is also worthwhile to explain the complexity of the context of past decisions that might have been difficult to make.
Finally, Birgitta Böckeler proposes some hints on how to deal with the main documentation issue: keeping it up to date when things change.
Her conclusion is that “If you’re somebody who tends to create a lot of documentation, and you want to reduce some waste: A focus on the value documentation will help you prioritise. If you’re somebody who creates very little documentation, reflect on if you’re missing some of the values mentioned, and what types of documentation would improve your team’s effectiveness. ”
Read the two parts of blog on https://www.thoughtworks.com/insights/blog/four-goals-agile-documentation-part-one and https://www.thoughtworks.com/insights/blog/four-goals-agile-documentation-part-two