I thought that by nowadays two main consensuses had been established towards requirements. The XP-ish “waste-of-time” school of thought that pretends this stuff belongs to NASA and similarly priced development and clearly are NAH (Not Applicable Here). And the “we-need-them-right” school of thought that believes in properly written and managed requirement documents.Of course, I am biased, I belong to the second school since I don’t buy the XP gibberish and I am a firmly believer that a sound methodology may not be The Solution to all software development troubles, but it is surely part of it.
So I am a bit surprised when I received a 35 pages requirements document that’s actual crap. Joel Spolsky wrote a sort of basic requirements for requirements in four parts. Well below is my list. I don’t want to compete with Joel (really, do read his post, even parts 1 and 2 and 3, it’s worth), but mine is shorter and should fit even in a tight schedule should you be requested to write specifications.
Think of it as a baseline rules of thumb:
- start by describing the system to which the specification refers. What it does, which kind of existing systems do more or less the same.
- don’t go ahead. These are specification, not software design. Leave out the “how”s.
- define every acronym you are using. Not everyone knows even the most basic acronym, left out the more exotic ones (I’m still wondering what “TBP” does mean). Also define terms that are meaningful only for those who already knows what you are talking about.
- list requirements in a way you can refer to them. Number them, or better use textual tags so that you can refer them in the same document or in the documentation that is following.
- Don’t use the following words: “some”, “etc.”, “good”, “bad”, “fine” and the ellipses. The idea is that you have to be precise and define the entire system without leaving open holes.
- use a spell checker. It’s easy, every modern Word Processor has it, just switch it on and fix the words underlined with the red snake (you should really do this for everything, not just the requirement document).
- re-read everything. People is going to read and work on that document, just re-read and fix, iterate until you don’t fix anything.
As trivial as they seems, all these rules were broken at least once in the document I was handed.