Working documentation - the perfect complement to working software


The Agile Manifesto is often challenging for organisations and individuals starting their Agile journey. In my experience, the Agile value that causes the most confusion and generates the greatest discussion is:

Working software over comprehensive documentation

The reason for the confusion is that this value reminds us of so many undocumented or poorly documented projects which were thrown together and then became a nightmare to maintain and extend. Documentation is important, right?

The key to understanding this Agile value is that we value working software over comprehensive documentation, not instead of. Documentation is still important, but it is not our primary purpose or measure of progress.

What and how much to document

We all know projects with documentation that is never reviewed or used - that's out of date the moment it's written or a dream based on wishful thinking that bears no resemblance to the work the team completes. There is no value in documentation that no one ever sees. We need to consider what and how much documentation should we be doing.

There are two things to remember. First, our documentation should serve the needs of the team, the project and the customer (both the end customer and the organisation) - anything else is a waste of effort. Second, we value living documentation over archival documentation. I call this working documentation.

The features of working documentation are that it is:

  1. visible
  2. living not archival
  3. accessible
  4. useful.

Below is the model I use for thinking about comprehensive documentation vs working documentation. It will help you focus on documenting what is most valuable to your team, project and customer.


Making documentation visible

Kanban tells us that the first step to improvement is making the work visible. I have seen the impact of this time and time again. Once the work is visible it suddenly becomes obvious where the bottlenecks are, what needs more resource and how we can improve our workflow.

Is it even possible to make our documentation visible? Yes - we are often already documenting our products and process visibly. Standing in front of our scrum board, we might see the work in progress, our historical velocity and our definition of done.

What is the impact of making our documentation visible? Check out the examples below.

Example 1: System block diagram

System board

Here is an example from a team I worked with a couple of years ago. In a retrospective, the team identified that there was a problem with technical debt in the project. The problem was not the amount of technical debt, but the visibility of the debt to the wider team. Developers would see areas that could be refactored or tidied, parts of the system that needed upgrades and broken tests as they worked in different parts of the system.

However, there was no way to share this with the wider team to support good decisions about how much maintenance and refactoring was needed and in what areas.

The team decided to create a system block diagram to document this information, updated as needed and situated next to the scrum board.


The diagram has many layers of information. The base level, the block diagram of the system, shows the different components, how they are connected and their current version. Different coloured sticky notes denote whether a component needs upgrading, smells bad or has a critical bug. On the stickies themselves we tracked when the issue occurred and when it was fixed.


The impact of this board was significant for the team and the project. Immediately the product owner could see, relatively, where the technical debt resided in the system. It prompted great questions and even better decisions. The team could easily determine determine a response to questions such as: if a component has an upgrade available and has been a source of critical defects, would upgrading and refactoring improve the dependability and quality of the component, or has the new version provided an opportunity to simplify or consolidate code or functionality?

If two components are combined, a team member could grab the whiteboard eraser, erase and redraw. The information was immediately available to the team and the business - no delay.

This example of working documentation decreased the cost of change, both perceived and real, on the project. Documentation was not seen as a compliance cost for the team; rather the quest for quality drove what was documented documentation.

The system block diagram met all the requirements for working documentation: it was visible, living, accessible and useful.

Example 2: ReadMe.txt files

Another piece of documentation that I consider working documentation is the ReadMe.txt file. Historically used for installation and change notes in commercial software, the open source software movement has identified ReadMe files as important pieces of documentation.

The ReadMe.txt file has the benefit of being within the developer's and tester's natural workflow - a plain text document under version control with the rest of the code. This small fact makes the ReadMe one of the most useful pieces of documentation that a project can have. It's easily updated and available to everyone on the project. The cost of change is very low as the use of plain text ensures that time isn't wasted on styling and layout.

Wikis are another core documentation tool for many projects today. They share many of the features of the ReadMe.txt file. Usually in plain text (perhaps using markdown), they can be collaboratively edited without a large overhead of file management and version control.

Like the system block diagram, ReadMe files and wikis are working documentation: visible, living, accessible and useful.


Take a look at the way your projects are documented. Is your documentation regularly used by the team and the business? Is your documentation up to date? Are documentation decisions made by the team and business in collaboration?

If you answered no, then it's a good time to re-examine your understanding of the Agile value 'working software over comprehensive documentation' and implement working documentation in your projects.

Learn more

The Board Agile talk show episode 14 — Agile documentation and preparation