How to write a specification for custom software

The ten-question test

Before sending anything, there is a simple way to know whether your document is good: have it read by someone who does not know your business, and count their questions.

If they have a hundred, the document is incomplete. Suppliers will answer with cautious quotes, padded to cover what they did not understand, and impossible to compare.

If they have none, they have not read it, or the document is so vague they can project anything onto it. That is the most dangerous case, because it produces low quotes followed by change requests.

If they have about ten, and those are about edge cases rather than the principle, you have a good specification. It is precise enough to be priced, and open enough to let the supplier propose a solution.

That test beats a proofread, because it measures the only thing that matters: what the document actually conveys to someone without your context in their head.

What the document is really for

A specification is not there to describe software. It exists so that several suppliers understand the same need, price the same thing, and can be compared on something other than a headline figure.

It is also, and often primarily, an internal exercise. Writing down what you expect forces you to settle questions left open for years: who approves what, which rule applies in which case, which information is authoritative.

Many companies find the writing gave them more than the document did. That is not a side effect, it is half the point.

Seven parts, and the two that count

Ten to twenty pages is plenty for an ordinary project. Beyond that, volume hurts readability and nobody rereads it mid-project.

• Context: who you are, what you sell, how many of you there are, how the work is organised today.
• The problem, with figures: how long, how often, how many errors.
• The users: who will use it, in what conditions, with what hardware.
• The journeys: what must happen, step by step, in the most frequent cases.
• The business rules: what is allowed, forbidden, conditional, with the exceptions.
• The existing systems: what the tool will have to talk to, and who administers them.
• The constraints: deadline, indicative budget, regulatory obligations, mandated hardware.

The journeys and the business rules alone represent half the document's value, and they are the two parts nobody but you can write. The other five can be drafted by anyone in the company.

Writing a journey, writing an exception

A well-written journey fits on one page and always follows the same shape: who, in what situation, does what, and what happens next.

An example, deliberately generic: "The technician finishes the job. They open the record, enter the parts used, take two photos, get the customer to sign. The record goes to billing. If the customer is absent, it goes to pending approval."

Four sentences, and a supplier understands what to build, what to connect, and where the special cases are. One journey at that level beats twenty lines of features.

Special cases deserve particular attention, because they are what makes the price. A general rule is written in one line; the situations where it does not apply are the real work, and they belong in the document rather than surfacing mid-project.

Write the most frequent journeys, then the two or three exceptions that come up most. Rare cases are handled along the way: seeking exhaustiveness at the start lengthens the document without improving the quotes.

Why exceptions weigh so heavily on a budget: what custom software costs

What is better removed

Three very common contents degrade the quality of the responses you get.

• Technical choices. Naming a language or a database deprives suppliers of their best contribution and gains you nothing. Describe the real constraints, not the solutions.
• Detailed screen mock-ups. They freeze an interface before the journeys are understood, and move the discussion towards appearance.
• Feature lists without context. "User management" can mean two days or two months of work. Without journeys, those lines cannot be priced.

A fourth temptation is worth avoiding: describing what the software you saw at a competitor does. You will get quotes for that software, not for your need.

One day, and someone who decides

For an ordinary project, a useful specification is written in a single day: a morning of observation in the field, then one session writing the journeys with the people concerned. It is not a document to mature over weeks.

The person writing it does not need to be technical. They do need the authority to decide, because the exercise will surface internal disagreements previously worked around.

If the writing feels heavy, there is an alternative: have the framing done by a supplier, while keeping the freedom to consult others afterwards. One day led by someone who has framed a hundred projects often produces a better document than three weeks of internal writing between other duties.

Finally, accept from the start that the document will change. Projects that land reread it halfway through and own the differences, because real use teaches things the writing could not anticipate. Keep the journeys and the rules as a living reference; the feature list will move.