“There is no documentation in Agile!”
Documentation is one of those necessary evils in software development, particularly for teams that use remote development centers and need to rely on written communication more. We periodically hear the excuse, “We are doing Agile — we don’t need no stinkin’ documentation!” This is a misinterpretation of the Agile Manifesto, which states, “Working software over comprehensive documentation.” It does not say that you should avoid documentation — it just values the working software first. Additional documentation is waste, which violates a critical Lean principle (eliminate waste).
Recently we had a question from one of our fantastic clients around how much of the existing architecture should be documented and how much documentation to produce moving forward. For context, this is a team that is practicing more of a hybrid development model, which leans more towards Agile than Waterfall. The conversation was lengthy, but below are the key points.
How much documentation is enough?
The first question I would ask is, “Why are we documenting the existing architecture?” Documenting existing design is not a bad thing — don’t get me wrong — but we have to understand why we are doing it to determine the best way.
Examples of other questions I would ask before undertaking an architecture documentation task:
- Who is the audience of the document?
- What is the minimum amount we can do to meet the needs of that audience?
- It is worth the effort to do retroactively, or should we focus iteratively on diagramming new features and building diagrams for existing features incrementally?
- Is the business value of producing this documentation worth the effort? (back to the “minimum” question)
- Are there specific pieces of the architecture that are difficult to understand? (If so, I would focus more detailed diagrams and explanations there)
- Are there particular pieces of the product that are bug farms? (it may be that engineers don’t understand it and it needs clarifying documentation)
- Are there specific pieces of the architecture that change more frequently and thus, require a greater understanding?
- Are there specific pieces of the product that no one knows due to attrition? (if the organizational change is planned, may want to document that as an exercise)
Some of those questions (and more) can help get to the minimum set of requirements and plan to document the architecture.
Is the documentation useful?
Once we start expending effort in producing the documentation, we need to measure its effectiveness. At one client, we documented their development model on a SharePoint site. It turned out that very few people ever referenced it outside the author and one or two other people. We measured accesses to the site, which documents were accessed, the number of changes per week and other metrics. Using this data, we determined that the effort wasn’t entirely useful and did some re-thinking around medium, internal marketing, target audience, and other factors to enhance visibility and usability.
The key to making this decision was the metrics. Have a plan in place for your documentation and measuring its usefulness. Think through the questions you want to answer, and the required parameters to answer them.
Will it be updated?
Another critical question is whether the documentation will be updated once it is produced. If it becomes stale, it is far less useful. A few keys to ensuring updates:
- Make it easy to update
- Schedule time to update, or better yet, build doc updates into the culture (e.g., part of the “done” definition for a user story)
- Provide incentives to update
- Ensure the documentation is useful to begin with
We’ll have more to say on documentation in the near future.
