It is an unfortunate state of our industry that I've worked on a large number of projects over the years but the quality of the specifications (if they existed at all) has been poor. Here are ten rules for creating decent specification documents, in no particular order. They all begin with the statement, "A decent specification is one that..."

1. Exists

If I had a dollar for every project I was on that contained zero written pages of specification, well, I'd be pretty poor, but the fact remains that a large percentage of projects simply have no written specification. Loads of reasons are given for this oversight (the requirements always change, there's no time for specifications, there's too much to document (!), etc.), but none of them outweigh the return on investment of actually knowing what you're writing.

 2. Describes What, Not How

Many specifications have screenshots, pseudocode, and other things in them. These are all solutions to a problem. The specification should not describe how to fix the problem, just what the problem is. I will not pretend that this is an easy task, because it isn't. It's especially difficult for software engineers who (usually) will immediately try to figure out how to solve a problem. One can only describe the "what" of a problem after some experience.

 3. Can Be Interpreted In As Few Ways As Possible

This one is vital. If the specification is ambiguous, it isn't really worthwhile. If software engineer A thinks it says one thing, QA tester B thinks it says another thing, and the customer thinks it says something else entirely, I can guarantee the solution will never solve the problem it was designed to in the first place.

 4. Is Widely Distributed

Everyone on the team needs to have access to the specification. This includes QA staff, managers, and especially the customer (in addition to the engineering team and whoever is writing it). Without access, everyone will have their own idea of what the software is supposed to do.

 5. Is Agreed Upon As Being The Spec By All Parties Involved

There can sometimes be competing interests in a project, especially if the project has broad appeal. Group A has its goals and group B has its, and the two may not be congruent. If everyone agrees that whatever is in the spec is the way the software will work when its done, you can avoid the incongruous goals of disparate groups (or, at least, force them to agree to some sort of compromise before any code is written).

 6. Is Concise

Wordy explanations and jargon-filled specs only confuse people. Only say what is necessary to describe the problem, and no more. Use language the average person off-the-street who has no knowledge of your problem domain can understand so that new software engineers to the project can come up to speed quickly.

 7. Is Consistent

If something is mentioned one way in one place, say it the same way everywhere. Or, better yet, refer the reader to the prior explanation. Inconsistincies in the spec will manifest themselves in engineering problems down the road.

 8. Is Updated Regularly As Requirements Change

It's a fact of life in the software engineering world that the requirements are going to change. People change their minds. Customers are lost and gained. Those are the facts of life. What this means, however, is that someone is going to have to take on the job of maintaining the specification and time (and money) will have to be budgeted for that work in the project plan.

 9. Describes As Much Of The Problem As Is Possible And Practical

Gather as much information as you can when writing the specification, but if you can't get any information about how a certain piece should work, leave it out. As long as it isn't a key piece of the overall problem, it probably won't affect anything and can be added later. On the flip-side, for things that are well-known, describe enough so that a software engineer can design a solution that will work.

 10. Is Testable

Everything in the specification should be testable in some form. How else will you know if the solution provided solves the problem if it can't be tested? You won't and neither will the customer, and you'll be left to haggle over that last payment.