On writing a spec
Good specs force the difficult conversations to happen before they are expensive.
If you hand a good spec to a builder or a programmer, the chances that you get back the system you’re hoping for are dramatically increased.
For a building, the spec is architectural plans. But give an architect a good spec and she’s much more likely to design a building you’d be happy to live in.
This post is mostly about computers and other complicated systems, but the thinking can be used for just about any project where you and your team are asking a system to solve a problem for you. Unlike buildings, computers and other systems change their state all the time, depending on what just happened and what’s supposed to happen next.
The spec outlines the inputs to the system and the outputs it creates. If it’s simple, it’s easy to write:
Put a quarter into the gumball machine and turn the crank.
A gumball comes out.
So, at the highest level, we have problems and solutions. I need a gumball is the problem, and the solution is to use this machine to turn a quarter into a gumball by releasing one from an inventory.
It gets a bit more complicated when the state of the system might change as the result of previous actions. For example, if the machine is out of gumballs, my spec requires that the quarter be returned. Knowing this, I could also add to the spec that the machine should know how many gumballs are in inventory, and how fast the sales are, so that when it has two or three days of inventory left, it sends a message to headquarters to ask to be refilled.
Inputs and outputs.
It’s worth noting that my spec doesn’t have to include any information about what gumballs are for, or how much it costs us to make gumballs. We’re defining the inputs and outputs of a system.
[It’s totally worth having a different discussion with a different team about your processes, your goals, the people you serve and the problems you seek to solve. Systems work best when they are coherent with what you actually seek to achieve… but we can leave that for another day].
It’s tempting to nail down the precise solutions to each input and output requirement early on. You might decide that the way you’re executing your system should be part of the spec from the beginning. That’s backwards. The system exists for solving problems, and the way the system executes is only there to serve that goal, not the other way around.
Maybe you don’t need a 386 processor or a tin roof to solve your problem. Let’s figure out the problem first, and worry about the way we meet your specs second.
Grab some index cards and simulate your system. Have each user write down precisely what they want to tell/ask the system and have the person running the system hand back index cards with the results that they can expect. Be clear about the state that the system is in before each transaction and after it as well.
The sum total of these interactions is your spec.
Bound this with constraints of time and money and performance and you’ve done the hard part.