I’m sure you’ve heard someone say something to the effect of “If it’s not in writing, it never happened.” There are good reasons for that, particularly if the work is being done for a paying client. The problem is that the concept is often carried to extremes.

If you need to hire someone to keep up with documentation changes, you’ve gone too far. There is a sinister cascade effect that can bog down development teams. It goes something like this:

A change to the requirements forces,

a change to the functional specification forcing,

a change to the technical specification forcing,

a change to the test plan forcing,

a change to the user documentation.

Another sinister problem lies in creating lots of pretty documents. It’s not enough to merely capture information. It has to conform to a documentation standard and be formatted properly. It can easily take more time to pretty-up the information than it did to capture it.

Don’t go crazy.

Consider longevity. Much of the information software development team generate has a limited lifespan. It may only be useful for the duration of the project. If so, why spend much time on it? If the information is expected to have a long lifespan, then it makes sense to invest the time to make it clear, concise and appealing.

Focus on content, not appearance. There are many ways to capture content from simple camera snapshots to elaborate and formal documents. Always aim for the simplest information capture approach. When you’re trying to be agile, less is more.

If your client, stakeholder or manager demands comprehensive and beautifully formatted documentation, you’ll have to comply. Let him know what the impact on time and cost will be and plan accordingly. In all other situations, don’t go crazy.

Intro

Welcome to BrainsLink.com - a blog written by Vin D'Amico about enterprise agile and its use in software development and business operations with occasional forays into open-source software and emerging technologies.