System specifications are even more unreadable and useless than business books. I don’t mean because they are boring, which they obviously are, and often poorly written in a language that combines ordinary words with business and technical jargon. Rather, they’re unreadable and useless because they don’t serve their purpose. They fail as descriptions of systems.

The system specification occupies a sacred spot in the evolution of a software implementation project somewhere between requirements analysis and system building.

First, you find out what the customer wants, you write these requirements down and then you get the customer to confirm that you’ve understood the requirements by reading your notes and signing them.

Then you retreat to the turret of your castle and there you specify the system. It’s a kind of alchemy. You take the raw material of what the customer wants and transform it into something (potentially) marvellous using your own special knowledge, experience and skills.

And then what?

Well, at this point the customer is supposed to read (and understand) what you’ve written, and sign his or her acceptance of the design. By doing so he is often also signing away his legal right to ask for changes.

The trouble is that the customer usually has no idea what you really mean by all your alchemical formulae. He’s like someone who can’t read music being presented with the musical score of Stravinsky’s Rite of Spring. He will have no idea what it sounds like.

You have described the system using the language of the software that you know and he doesn’t, showing screenshots from the system that you know and he doesn’t, and the document is so long anyway, and so dry, that he can’t possibly know what he’s really signing up to.

Of course, there are better ways. Customers (end users particularly) should get a chance to play with a system before they sign off on a prototype (together with the document that’s supposed to describe it). There’s then a much better chance that they will know what you mean. Granted there must be some kind of document (more for your own purposes than the customer’s) that documents the design, but what the customer should be exposed to is a kind of prototype, a moving model, that you and he refine over a series of meetings.

This is the ‘agile’ approach to system implementation, a method inspired by the ‘agile development’ method used for software development. Perhaps, using methods like these, there will be fewer occasions when you end up building a monster and hearing the customer say, ‘But that isn’t what I meant at all!’