Writing specifications

Shock horror! I’m actually posting something here about software design. Well, try and adjust: I’m going to be trying to shift things in this general direction in the future. No guarantees on just how often these posts might come about.

So you know, this is partially a reaction to Joel Spolsky’s (2000) 4-part article, Painless Functional Specifications. Excellent reading. Indeed, it’s probably best to be reading that first (all four parts). I’ll take “quality specifications are a good thing” as assumed here.

Now, as I see it, an intended user of a specification should want to pick it up and casually read through the whole thing.

Spolsky offers a number of tips for writing a specification that all its intended users want to read, and these seems solid.

Basically, if an intended user doesn’t feel like casually reading the whole thing, I see five possible results:

  1. They read it out of a sense of obligation and duty (“Someone’s gone to all this trouble to write this spec, I really should read it). In which case they’ll probably skip all the parts that they think they already probably know and anything that seems boring, and probably won’t thoroughly digest the rest of it.
  2. They read it because they’re bored and see an email attachment which they could kill 10-15 minutes by reading – for much the same result as a).
  3. They only read it when they want to find out how the user is notified that the input is invalid (or whatever). In which case all you can guarantee the specification to have achieved is that some people might know some things about some parts of the system (aka “we’d all have been better off playing Solitaire”).
  4. They don’t read it.
  5. They open the Word document, glance at the heading, scroll through the rest of it in the same way they probably read the MS Office EULA (ie. without actually looking at it, but maybe they notice some formatting), say “that’s nice” and close it. Which is effectively the same as d).

Note that I’m saying here that I have to be able to take the specification and want to read it on the bus ride home in the same way I might want to read a new Tom Clancy thriller, the point is just that reading a specification should be seen as something constructive, enjoyable and worthwhile.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: