by Shaun McGee

Shaun is a Lead Consultant with ThoughtWorks Inc., and hence my esteemed colleague. Like other ThoughtWorkers he is strongly opinionated about Agile principles and practices and he spares no chance to explain his stance on stuff. In this particular article, Shaun discusses candidly the role of documentation in software projects. Shaun cites how there is a qualitative difference between documents produced at different stages of a project and we better start recognizing those differences  now!

Introduction
“We have come to value…working software over comprehensive documentation.”
The Agile Manifesto speaks to the importance of focusing effort and attention not on the documentation we produce, but rather on the functioning product that results from our work.

Why do we write software documentation?  Traditionally, it was accepted that by thoroughly documenting the “what” (requirements) and the “how” (specifications) we would be able to effectively develop some software, much like the way careful planning and design can produce a bridge or a house. Unfortunately this just doesn’t work most of the time. You can spell out in great detail what an application should do and how the development team should produce it, but what we often find is that as the system grows from an idea into lines of code the underlying requirements evolve or the original specification turns out to be impractical or impossible.

For this reason many agile practitioners (like ThoughtWorks) recommend keeping the documentation to a minimum in favor of face-to-face conversation. While there might be a temptation to discard documentation entirely, we know that’s simply not practical; we need some level of documentation as a consumable for later steps in the process. Indeed the complexities of some organizations and the regulation of some industries may require substantial documentation to describe a software system as a deliverable. The important point here is to recognize which purpose (consumable or deliverable) it serves.

So if we’re not going to use these “specifications” to drive the development process, what will we use them for?

If the reason we need some thorough documentation is to satisfy a customer or internal stakeholders, then we should prepare documentation that frames the system in their terms. This might take the form of a user manual, detailed feature description, or training materials. If the purpose is to satisfy some regulatory requirement, we should produce system specifications that comply with that need. In both cases we’re talking about a description of what the system does rather than what we intend for it to do. That’s an important distinction because it can help us to divorce the tasks of “producing documentation” from the process of “conducting analysis” where it has traditionally been tied. The bottom line is that the types of documentation that are suited for these needs are often not useful as a blueprint for software development, nor do traditional requirements specifications typically reflect an accurate picture of what a system is unless we put extensive effort into maintaining thorough version control.

So if we’re not producing documentation up front, when will we do it and who should write it?

Why not make the production of supporting documents a discreet task that is part of the lifecycle of a user story? Let’s say a story typically flows through the following stages:

While there should of course be constant communication and collaboration across the team throughout the entire process, there is a team member who has primary responsibility for pushing the story forward at each of these stages. During the Analysis stage, a story is defined and molded by a Business Analyst. In the Development stage, software craftsmen (developers) turn the idea into working code. In the Quality Analysis stage, test professionals scrutinize the software and try to break it! The customer then evaluates the finished product to ensure it meets her needs and certifies it is Complete.

Let’s imagine that you can add an additional step in the process:

Once a collection of related stories reach completion, we can start to consider application features to be reaching a level of maturity. We can take this opportunity to document how a mature feature functions within the system. This can and should happen soon after these stories are completed. We would not, for example, wait until just before a release. If the team is working collaboratively, we should expect anyone to be in a position to contribute to to documentation. Try a wiki approach that allows the entire team to contribute to a holistic view of the system; team members who play different roles would likely have unique perspectives.

“Simplicity–the art of maximizing the amount of work not done–is essential.” (Principles behind the Agile Manifesto)