Usually, most programmers don’t like reading specifications. They like writing them even less. Specifications are always incomplete, incoherent, give stupid advice on things which are better left for the programmer to decide, boring, official, out of date, thrown away when the project is complete, generally a big waste of time. Does this mean that functional specifications are inherently a bad idea and you shouldn’t even try? Of course not! It only means that you’ve never seen a good specification or how it’s used.
What, then, makes for a good functional specification? I’m going to crystallize it into just one rule:
A good spec is actually being read by all stakeholders.
This simple rule implies a number of important effects. Because everybody reads the spec, you’ll actually get feedback early, which is what the specs are for. Since everybody reads the spec they all know what to expect and the chances of you project to be deemed successful rise dramatically, which is also what the specs are for.
How do you know if your spec is being read? That’s actually surprisingly easy to measure. If someone gives you useful feedback, that person has probably read at least some part of your spec. If you get no feedback from anyone, you can bet your grandma’s false teeth that nobody read it. They probably didn’t even click the link you sent them. Instead, they updated their Facebook status or reorganized their paper clip collection — any number of things are more interesting that reading the average spec.
Let me make this into a rule as well, just so you can pretend you’ve read this by only reading the cursive bits which stand out:
Your spec is being read if you get feedback.
The hard part, of course, is getting people to read the specs in order to get that feedback. For that to happen, the spec must be really good. It must not be boring to read, for example. The best guide I’ve seen for writing good specs is Painless Functional Specifications by Joel Spolsky.
I’ve never written a spec and received any significant amount of feedback. I’ve mostly written technical specifications. Once, I thought I did a really good job on one. I thought my spec was concise, covered all the relevant aspects, and was easy to read. I even put in a joke or two. Nobody ever read it. That was giant flaw number one with my spec: I never got anyone to read it and got no feedback. Giant flaw number two, and the thing which makes giant flaw number one much worse, was that I didn’t even write the code myself. I did all this design work, had everything planned out nicely, and then someone else steps in, ignores my spec, and bangs out whatever design they damn well please. But I digress, tech specs are a different topic.
I will be writing a functional specification in the next few weeks and will be revising it throughout the year. I don’t know yet how to get anyone to read it, but at least I know that’s the most important thing the spec will be for and I can concentrate my efforts accordingly.
If you liked this, click here to receive new posts in a reader.
You should also follow me on Twitter here.
Comments on this entry are closed.