Minimal IT logo and link to home page
Research, training, consultancy and software to reduce IT costs
Home | About | Newsletter | Contact
Previous | Next Printer friendly
15 January 2008

Perfect testing, perfect documentation

By Andrew Clifford

If you think of testing and documentation as just tasks on your plan, they will be near worthless. If you rely on them as the authoritative specification of your system, they will be near perfect.

Most IT project plans include testing and documentation.

Often they succumb to project pressures: testing gets shortened, and documentation gets dropped.

When we have the opportunity to do them well, we think of them as processes. We have processes to define and execute tests. We have processes for writing, reviewing and signing off design documents.

But thinking of testing and documentation just as project processes is not enough. We need to take them further.

Many years ago, testing was synonymous with debugging. Testing was a way of removing defects. Ideas developed, and testing became a way of proving that requirements had been met. Ideas developed further with test-driven development. Tests are part of the evolving specification of the system, especially when delivered as automated test packs.

In my experience, something similar has happened with documentation. Years ago we used to write one huge document per project which described every aspect of the design, but which was not kept up to date. As designs have become more modular, the focus of documentation has shifted to the individual components of the system, so that they can be reused and extended.

Testing and documentation have matured from being just a hurdle in the way of implementing a system to being part of the final deliverables of the project. This is a good progression, but we need to take it one step further.

The next step we need to take is to turn our perception of documentation and testing around. Instead of seeing them as something we try to keep up to date, we assert that they are, by definition, the authoritative specification of the system. If the system functionality differs (for example because someone has not updated them after a change), then the system is wrong. This means that there is no such thing as out-of-date documentation or incomplete test packs, just system errors.

To achieve this, you have to rely on your tests and documentation. If you habitually read code before looking at documentation, your documentation will be worthless. If you test modifications just by throwing some production data at the test system, your tests will be worthless. Conversely, the more you use and rely on documentation and tests, the more reliable you will make them.

Treating testing and documentation as authoritative is part of the maturing of IT.

When IT was young, it made sense to dash for growth. Testing and documentation only had to be good enough to get to implementation.

But the dash for growth is over. The emphasis has shifted to the ongoing management of IT. Documentation and testing support the gradual evolution of systems, and are much more important than they were. To be effective, we have to stop thinking of them as nice-to-have parts of projects. We have to treat them as the perfect, authoritative specification of the system. And the more we rely on them, the more perfect they will be.

Next: Work less


To subscribe to the newlsetter, simply send an email to
Privacy policy

Subscribe to RSS feed

Latest newsletter:
Your first web app

With a unified approach, creating a web app is as easy as creating a web page.
Read full newsletter

System quality management

System quality management helps you implement high-quality systems, manage existing systems proactively, and improve failing systems.
Find out how