A Rough Guide: Software Specification

Software Development can be like going on a holiday to somewhere new. You always run the risk of getting very little sun, potentially ending up in a grotty hotel or getting messed up by muggers and left groaning and penniless in a filthy, urine saturated alleyway. So how do we avoid this scenario and make this holiday the one where we meet up with our new found holiday friends, knock back a few nostalgic caipirinhas and congratulate each other on what a brilliant time we all had?

The key is in the right technical planning.

A core part of the technical planning process is The Software Specification. So what makes a good spec? What makes a bad spec? And for the late arrivals, just what is a spec exactly?

I’ll attempt to answer this through a continuation of the holiday metaphor - oh, how I do like a metaphor (or, in this case, a simile). A Software Specification is like your travel guide. It can tell you what to do, how to do it and where to go to get it done.

Specs vary to many degrees in detail and focus.

You have your Rough Guide specs which keep it high level. Rough Guide specs appreciate that the traveller is capable and provides him or her with a recommended path and expert ‘advice’. The focus is on the highlights and leaves the mundane detail to when you get there. A good traveller taking heed of the guide’s good bits - and occasionally ignoring the bad ones - will most likely have a good journey. An ignorant traveller will attempt to ask the group of hooded men how one gets to the nearest Planet Hollywood as they have a wad of Deniro burning a hole in their pocket. Battered. Gutter. Urine.

Other specs are more prescriptive and effervesce with implementation detail. They are like package holidays where you are - for better or worse - locked into a rigid itinerary. Like package holidays, over-detailed specifications can lock developers into a poorly thought out design that makes for an unpleasant ride. This is especially relevant for new, large scale builds where it is impossible and ultimately counter productive to attempt to work out everything before you actually get there.

Considering two variations, the Rough Guide Spec is what I consider, in most cases, the best accompaniment for development builds.

Here are my top tips for writing a Rough Guide Spec

Don’t get bogged down in detail
Getting bogged down in detail too early will prevent you from that all important birds eye view. Start off with functional requirements then drill down through use cases to annotated wireframes (if there is UX involved) and, lastly, application structure and class design. The latter can often be achieved by creating the solution skeleton rather than laboriously transcribing documentation into code. Having the top half of the spec ironed out is crucial as this is often what forms the client sign off and the big angry dog you get out when scope creep comes a’knockin.

Know you can do it before you spec it
Writing a light spec which can be backed up with hands on assistance if required is crucial. In a lot of cases you will have to discuss the implementation with developers and it helps if you have a clue. A discussion is a better forum for implementation detail since it allows brainstorming and developers to provide their own feedback and gasps of disgust.

If you don’t know it, POC it
This is kind of related to the last tip; you, as a spec writer, will oft come to a point where you’ve run out of knowledge, wikipedia doesn’t have a page and you know bullsh!t will come back to haunt you - generally in the guise of an angry developer with fast ebbing respect for your technical nous. In this case POC is essential.

POC is Proof of Concept by the way, not Pan O Chocolat. Although, that would be tasty.

Be Open to Change
This one is simple, be open to better ideas as chances are they are out there!

So that’s it on tech-rash’s top tips for spec writing.

Happy Holidays!