Specification documents are boring

Have you ever read a specification document? I did today and I was reminded why I don’t like them.

They are boring. Even when they are telling you something you didn’t know they are boring.

They are boring because they follow the “form follows function” mantra. The function of a specification document is to communicate what one person wants (or thinks they want) to a second person who is responsible for implementing it. But there is more, the first person wants to specify exactly what it is they want, so thinks are set out in simple fashion, e.g. bullet points, no prose. Supposedly this limits ambiguity.

It also provides an audit trail so they can go back and see what has been done and what isn’t.

Yet in communicating from A to B they fail. They fail because they are boring and person B, the receiver, is going to switch off. The receiver is likely to read what they want to read, they will quickly get a feel for what they think the document says and proceed to read it like that. (Remember, the meaning of a message is decided not by the sender but by the receiver.)

Ambiguity still exists, in fact, because the document is so boring it can be difficult to pay attention enough to spot the ambiguity. And because everything is presented as bullet points it can be difficult to understand how the different parts hang together.

I suppose it does provide an audit trail but this is more damming than it is positive. We create an audit trail because we expect things to go wrong, we expect to need to trace back and apportion blame. So, we set up an adversarial relationship.

And when you’ve worked with a few requirements specification you know they are frequently the subject of battles so you don’t approach them with any enthusiasm. So you find them even more boring.

The result? Requirements documents fail on all counts; they fail to communicate, they fail to provide an mechanism for getting things done, they fail to enthuse, and they set up a bad work environment - so things are more likely to go wrong.

How do we fix this?

Well, I don’t have any hard tried and tested solution so these are just ideas:

• On site customer, this is what Extreme Programming recommends and it seems to bring benefits

• Close in Product Manager, if you can’t have a customer have a Proxy Customer, a Product Manager

• Use verbal communication in addition or instead of written, involve everyone

• Rather than try to specify everything down to the last detail allow people to engage on a voyage of discovery, involve them in finding the requirements

• Paint pictures and visions, allow people to flesh out the detail themselves

• Tell Stories

Stories are something that interests me. They are a topic I expect to return to over the course of this blog. In the meantime I’ll just recommend one book. It is The Springboard by Stephen Denning, Butterworth Heinemann (2001).