As a developer, I’ve seen a lot of specifications float across my desk. The quality differences between them is staggering. Sometimes you get a really nice specification document. Other times things are a complete mess. What bothers me most about some specifications, it that they aren’t “specific” at all. They leave way too much up to the imagination. They’ve left out way too many use cases.
The first thing I do when getting a spec is that I go over all the different use cases. I start coding the thing in my head, and start to think about all the different interactions the system will have. Most of the time, in the first 5 minutes I can come up with 2 or 3 use cases that the author of the spec didn’t even consider.
This is very frustrating, because, when the specification is a work in progress, it means that I must send back the spec to the person who wrote it up, and ask a whole bunch of questions to clarify or expand on the specification so that we don’t end up with a system that doesn’t do what it’s required to do.
When it’s not a work in progress, I just resort to slamming my head against the desk. Because what that means is that this specification has already gone across the desk of many other developers, and there’s probably very little I can do to get things changed, because then all the other implementations would have to be adjusted to fix the changing spec, and even if they all wanted to, the people in control of the spec think there’s nothing wrong with it, because everyone else has been using it for years and never come across a problem (or never bothered to complain).
Anyway, I think that the best thing you can do with a spec is to get as many people to read is as possible. Because other people reading it will find holes in the specification. They will find new ways of interpreting whatever it is you wrote, and they will make your specification more clear and more useful to other developers. Because nobody wants their project ending up like PHP.