Photo by aisvri on Unsplash
There is a lot to agree with in Leon Tranter’s Myths of agile: “there’s no documentation in agile”. And yet there is a new myth inside the debunking of the original myth. Among the many fine arguments supporting the use of documentation in Agile projects and advocating using Agile philosophy to determine how much documentation to do, when to do it, and other key questions, the article makes what appears to be a significant error in its justification. It says, “The best way to reduce ambiguity is by getting people to have a conversation, not by writing a 50-page document” because “conversations are a better way to get people to remember things” (emphasis added).
I don’t know that I can count the number of times I’ve had a team hold a conversation only to return to the topic at a later date and have completely different ideas about what was said or agreed. Very simply put, individual interpretations of events vary, creating ambiguity about actual events. The antidote is documenting conversations at the time they are held and circulating written summaries to all participants for review and agreement. If you don’t get agreement on a written summary, then you know that you didn’t truly have agreement in the conversation and that you need to follow up until real agreement is achieved.
In situations where a team had a genuinely common understanding at the time of the original conversation, it often happens that full recollection of that understanding at a later date doesn’t happen. It is easy to see that memories degrade over time and therefore become less reliable than written documentation. My teams have had situations where they could remember what a decision was or maybe that part was captured in writing, but they couldn’t remember why the decision was made the way it was and not a different way. Sometimes a team can piece together the reasoning based on their memories of the original events and sometimes they simply can’t and have to reconstruct the original analysis to remind themselves of their earlier conclusions – a clear waste of time.
Finally, in situations where a team relies on conversations with a subject matter expert (SME) to support analysis and decisions for a project it accepts a significant risk by not recording the results of those conversations as they occur. Individual sources may depart from the project or community and take unique knowledge with them if it hasn’t been captured by the team as it was discovered. With the departure of a key SME, projects can face the prospect of having to start over because they no longer have the expertise to explain an existing design or lead the emerging design that is based on lost knowledge.
As with straw-man arguments generally, the comparison of conversations vs. 50 page documents largely misses the point. There is a reason written history replaced oral history as the primary medium for recording human history and that it represented progress when it did. That reason is as true for documenting the analysis, design and implementation of systems as it is for world history. It is a tool for validating team agreements, more durable than human memory, and enables contributors and recipients to be separated in time. And you don’t need 50 pages for it to work.
For more about documentation in Agile projects, see An Agile Approach to System Documentation.
