Specs: The Consultant's MacGuffin

One of the major frustrations of working as a consultant is the love/hate affair with specifications. Far too often, I've come to the realization that specifications often fill the role of the classic Hitchcockian MacGuffin. tagentially, the project appears to revolve around them, but by the time the project is all said and done, it turns out that the specs were essentially ignored. A MacGuffin, as described as wikipedia is:

A MacGuffin (sometimes McGuffin) is a plot device that motivates the characters or advances the story, but the details of which are of little or no importance otherwise.

In order to generate a development quote, a set of specifications are needed and should be submitted along with your quote. Those specs are the guidlines by which the scope of the project and the necessary set of features are defined. In order to generate a set of specifications, however, one or more discussions with the potential client must take place (usually a good deal more than one). By default - because clients don't like to read technical documents - your potential client will actually base their concept of the scope of the project on
those discussions, not what's in the specs.

The dilemma as a consultant is: how much time do you spend on a set of specifications that no one (including you) are going to read? Even worse any quote you submit should be based on a set of features that you believe are in the project, so you should really have a set of at least internal specifications before putting in a quote. Thus they are the consultant's McGuffin - extremely important from an abstract sense but the details aren't all the important - think of the actual falcon statue from the Maltese Falcon or the glowing suitcase from Pulp Fiction.

The question then becomes, how do you make sure the time you're developing detailed specifications is time spent well?

One of my recurring nightmares (this is a literal nightmare, I wake up in a cold sweat whimpering) is coming in at fraction of the cost of competing bids, being chosen, and then either have to complete a project at a fraction of our normal hourly rate or having to go back to the client and say XXX (which is clearly mentioned at the top of on powerpoint slide 82 of their RFC) isn't included in your quoting costs. That's the sort of thing that can doom a project before it even gets off the ground.

A proper set of limber yet detailed specs can get actually help avoid this and a couple of other problems and keep your project moving in the right direction. One thing that keeps the spec process from dragging me down too far is remembering that, when it comes down to it, when done right they can actually be a significant benefit to us and not just a worthless piece of documentation.

The guidelines we try to follow with specifications are fivefold:

1. Write your initial quote in a bullet point, line item form generating only as much detail as you need to figure out how long a piece will take to complete.
2. Once your quote has been approved, expand on the quote from #1, but keep the detailed spec's short and sweet - the entirety of the project doesn't need to be explained in laborious detail, only the parts where you are concerned you and the client might not be on the same page. Everything else gets a bullet point.
3. Make sure that it focuses on the output of the project and actions that users can take. The client most likely doesn't care as much about how things are operating on the back-end on - what they care about is what they see and what they can do. By keeping the focus on interfaces and actions, it'll be easier to say know when the client is asking for something additional as it should be clear whether or not their request is included in the specs.
4. Take the time to go over the specs line by line with the client. Provided you followed #1 and #2 this shouldn't be quite as laborious as it seems. Even for some of our larger projects the specs are only 4-5 pages and a 1/2 hour conference call was enough to go over them in decent detail
5. Send an email to the client after #3 asking if there is anything missing from the specifications and give them a couple of days to respond via email - it's quite possible that you may have missed something, but you also want to have a solid idea of the scope of the project before you get started. This way you have on record that the client is happy with the features in the project as scoped, and any additional requests will be viewed as such by both you and the client - keeping everyone happy.
   
   

There's a #6 as well - but as we're in the process of putting it to the test I don't feel entitled to pretend like it's part of our normal process:

6. Turn the line items from you spec's into acceptance tests using a framework like Ruby's Cucumber, further gaining value from the initial spec work.

We're currently working out the benefits of this, so I'll let you know how it looks when it's all said and done.