Musing about Agile Documentation

Introduction

The Agile Manifesto (published in 2001) states “working software over comprehensive documentation”. Since then, this core principle of agile has been the subject of healthy debate. Rightfully, questions are raised around the value of up-front documentation approaches, the amount of documentation needed and the artefacts delivered.

The agile manifesto also states that, while there is value in the items on the right (documentation), we value items on the left more (working software). So, what value is there in documentation, and how much documentation is enough?

Discussion

The answer has little to do with documentation. The real question is how much information needs to be made readily available to stakeholders both inside and outside of a team in order to effectively communicate the functional and technical design. Examples of these stakeholders include the business, infrastructure, operations, security, risk, architecture, compliance and quality assurance.

So how should design information be shared with these stakeholders? The production code is the most accurate representation of how a system is built. For developers, code is readily available and easy to comprehend. However, as more teams are introduced, complexity of the codebase increases, legacy accumulates and the target audience shifts from developers to less technical stakeholders, using code as the communication tool becomes repetitive, slow and requires developers to continually “interpret” between the code and stakeholders. This overhead hijacks developer productivity and impacts velocity.

An example of how this manifests could be:

“Recently I needed to understand how an existing B2B web integration was implemented so that we could agree similar with a new customer. There was no documentation and the answer lay in the code, which needed a developer to investigate. This required a user story to be added to the backlog, prioritised in to the next sprint and finally I got the information needed almost two weeks later” – Presales Solution Architect.

​This effect is exacerbated as the number of teams working on a product and the number of lines of code increase. Scaling direct communication becomes increasingly challenging as more stakeholders are added (see a good video on this topic).

In order to avoid this, a level of documentation is required to bridge the gap between code and stakeholders. Succinct baseline functional and design documents that describe the existing as-is state of an application are key. Past states can be reviewed through historical versions and future states are better articulated through tactical backlog driven transitions to the baseline or strategic roadmaps that create, modify or deprecate services or capabilities.

Instead of debating whether documentation is required or not, this energy is better spent exploring how to document more effectively. Tools and techniques to produce more accurate documentations with less effort are maturing. Examples to take a look at include Swagger, Gherkin, Mermaid and Plant UML.

Organisational factors to consider

Various factors may influence the level of documentation you produce, examples include:

• The complexity of your software
• The type of development - are you building a one off solution, a product or a platform
• Geographic dispersion of teams and stakeholders
• The number of teams involved in the development
• The number of people in each team
• The number of stakeholders

Links

Here are a few more Code Project articles on agile:

• Agile software development methodologies and how to apply them
• Agile Programming
• Agile Methodology

History

• Version 1.0 - Submitted
• Version 1.1 - Minor formatting changes