Dying or living: the role of documentation in agile organisations

6. feb. 2014

"We don't do documentation - we're agile!" is a phrase heard much too often. The manifesto says so, one might be told: "Working software over comprehensive documentation." And so the agile project merrily starts out building things, sharing knowledge between the individuals on the team, creating working software, delivering value, and writing down nothing.

This "not doing documentation" is one of the things that terrify the organisations that are considering an agile approach. The problem with "not doing documentation" on an agile project, is that the project does not exist in a vacuum - most of the time there is a wider organisation outside the team. Furthermore, a digital project does not actually finish on launch. The project team will scale down, perhaps hand over to a support organisation and new people will be working on it. There will be bug fixes, new feature requests, support, and maintenance. Somewhere down the line, someone else might need to integrate with the new system, which by then has become the old system.

Not doing documentation means that the communication with the wider organisation suffers, often badly. So when the manifesto says "Working software over comprehensive documentation", and the agile team says "agile don't do documentation", what the organisation hears is "in agile, no-one outside this team will ever know what is going on".

What many teams fail to understand, is that the merry men who wrote the manifesto were referring to a specific type of documentation. The documentation they saw as wasteful was the thousands of pages of feature specifications, the pixel perfect page designs, the towers of progress reports, the essays of change requests, and the endless minutiae of keeping detailed project plans up to date. Specifically they were talking about the project documentation whose purpose is to be written, read, and acted upon, whereafter it is dead. This type of documentation has no ongoing value, it is dying from the moment words are put to paper. There is another set of documentation though that actually provides value throughout and after the project has launched though - the living documentation.

In some so-called agile projects, the consequence of "no documentation" is actually increased waste, as time and money is spent trying to recover lost knowledge.

To work out what you need to keep documenting in an agile world, think of what needs to live on outside or along with the current project team. The living documentation is roughly divided into three categories:

  • Current state documentation - What the code does right now. This should perhaps be called extracted documentation, because we are talking about the things that can and should be automatically extracted from the current installation. Tools can easily be set up to extract test names to tell you the features that have been implemented, and to generate database diagrams and architecture diagrams from living code.
  • Supporting documentation - the user manual, operations manual, logins to the servers, brief technical overview, information needed for operation and maintenance.
  • Directive documentation - The overall vision for the product, design guidelines, outside directives such as laws and regulations (or pointers to these) and directive decisions (such as quality beating number of features, or supported devices).

This living documentation is what the new team member, the product manager or support team can use to look up the current state of the product when the original team has dissipated, or when something has run successfully with no interaction for a year and the server needs a bit of love. It is also what the team uses to anchor development throughout the whole life of the product - not just the project phase. These are not static documents, set in stone and followed forever. The living documentation should be updated frequently by all who touch the software, and it is highly accessible within the organisation (though perhaps with some additional measures for sensitive information). The actual written material itself is generally brief, consisting of pointers, overviews and essentials. For any agile team, it is important that this sort of living documentation is not disregarded with a disdainful "we're agile - we don't do documentation". Because if you throw out all the documentation and not just the dead stuff, all you have done is introduce a new form of waste.