Documentation in Agile

Documentation in Agile is one of the most misunderstood aspects of the methodology. It is a common belief that those in an Agile workspace do not document or cannot fit documentation guidelines into the framework. This is (of course) false. When implemented correctly Documentation in Agile is not only possible, it thrives.

To begin let’s review what The Agile Manifesto says about documentation: 

One of the four values of Agile is ‘Working Software Over Comprehensive Documentation’ which states:

“Historically, enormous amounts of time were spent on documenting the product for development and ultimate delivery. Technical specifications, technical requirements, technical prospectus, interface design documents, test plans, documentation plans, and approvals required for each. The list was extensive and was a cause for the long delays in development. Agile does not eliminate documentation, but it streamlines it in a form that gives the developer what is needed to do the work without getting bogged down in minutiae. Agile documents requirements as user stories, which are sufficient for a software developer to begin the task of building a new function. The Agile Manifesto values documentation, but it values working software more.” (Beck et al., 2001)

What this value means to “green-field” applications:

In standard approaches (Waterfall) documentation can become unwieldy and outdated, negating hard work and delaying software releases. Because Agile values software over documentation, the goal is to keep documentation relevant and minimalistic but delivered as part of the release. This increases the likelihood that the documentation is accurate and aligned with the actual implementation. In “green-field” applications the team will design an Architectural runway at a high-level. Following this design the project is documented through a user story system incrementally and as needed. Having work documented within the requirements of a story allows the team to track progress from inception to completion in real-time, without the need to re-analyze and update required documentation.

In cases where official documentation is required, Agile teams should look at documentation as the implementation of software. If there is a business reason to document, then it is work that needs to be defined and managed in the same agile team process, but it has to be defined, estimated, prioritized, completed, and tested. A common misconception is an assumption that documentation is “free”, and it gets deprioritized, leading to incomplete and outdated documents.

Documentation that needs to be maintained should be treated just as software that would need to be maintained. Therefore this documentation should be treated as work for the team responsible for maintaining the software. This follows the concept that making changes is work.

What this value means to “brown-field” applications:

When addressing “brown-field” applications with legacy architecture a team will address historical design details as needed which keeps the documentation timely, valuable, and minimalistic. When the need arises to understand a part of the application to unblock a desired task the research work is defined as a “Technical Spike” and should be defined, estimated, prioritized, completed, and confirmed. In addition, it should be linked to the stories that it blocks so work does not prematurely start without the necessary information or resources.

The important takeaway here is Agile is inherently self-documenting that not only keeps documentation up to date but a log of changes as well. When official documentation is needed we must treat it as work and prioritize it as such. To simplify, documentation is not free it is developed along with the software and must be given the same consideration in regards to time and effort.