Documenting Agile Projects

John Newton's picture
John Newton

When we first started using Agile to manage our projects, we were delighted with the idea of valuing "working software over comprehensive documentation". In waterfall project management, documentation was used all too often as a way of simply mitigating risk. So reams of paper were wasted, as documentation bloated and became unmanageable in any practical sense.

Most developers dislike documentation - it's seen as a boring artifact of software development, as something that holds you up from actually doing something worthwhile. However, as Ashish Sharma has written, documentation should be:

  • essential
  • valuable
  • timely

At Sereno, we've thought long and hard about documentation and continue to iterate and tweak our documentation as we learn from succeeding projects. However, we have developed a fairly stable approach to documentation that I wanted to share. I think we document a lot compared some Agile developers. We don't do this to blindly follow procedures or to offset risk.

We use documentation to aid communication and to encourage creativity and thought.

For example, each stage in our project has a checklist which we share with our clients. This simple idea follows the kind of approach first encouraged by Atul Gawande. It's not strictly-speaking part of an Agile document set but it brings clarity and helps our clients better understand the process we're stepping through. We also document in plain English. We avoid the use of technical jargon in anything we share with our clients.

We also document loosely.

So we develop a plain English summary version of the Functional Specification. It isn't rigorous. It seeks to explain in simple language what the various aspects of the wider Functional Specification (user stories and so on) are all about. We also present it as a wiki type of document. It doesn't have neat categories but can be used to capture ideas and is fairly elastic in structure. After all, what's important is the working software we're building not the documentation - our documentation is there to serve the software.

Finally, a note about wireframes.

It's becoming more common these days to find companies that move to rapid prototyping and miss out wireframing altogether. Isn't this another document we can drop? I don't think so. It still fulfils the Agile requirement to be valuable. While Drupal is great for rapid prototyping, sketching with clients always beats prototyping in my view as it's simply quicker and more spontaneous - and so it's a better way of of aiding thinking. That said, it's just another tool to help us along the way. Once we've generated sufficient ideas, we move to prototyping and the ideas developed through the static wireframes will change and move on through prototyping.

Unlike waterfall, we don't fix ideas in documentation or use them to audit. They are stepping stones along the route to building better software.