If you have ever received a quote for software that felt like a number pulled from the air, the problem was probably not the developer’s arithmetic. It was that nobody had written down what was being priced.
A specification exists to make disagreement cheap. Every argument it causes before the build is an argument you are not having, at ten times the cost, three months in.
The parts that matter
- Who uses it, and for what. Named roles with the tasks each one performs. Not “users” — “the scheduler, who assigns jobs each morning and reassigns about a fifth of them by lunchtime”.
- The rules, including the awkward ones. What happens when a booking is cancelled inside the notice period? When two people edit the same record? When the payment fails on a Sunday? These are where estimates go wrong.
- What data exists and where it comes from. The fields, their types, what is required, what is unique, and what has to be migrated from the old system.
- The integrations, named. Not “connects to our accounting system” but “creates a draft sales invoice in Xero via the Invoices endpoint, matched on contact email”.
- What is explicitly out of scope. The most valuable section in the document and the one most often missing.
- How we will know it works. Acceptance criteria written as things someone can check, not adjectives like “fast” or “intuitive”.
What it does not need
It does not need to name a framework, a database or a hosting provider. Those are implementation choices and locking them down early removes options without adding certainty. It does not need pixel-level design either, though wireframes of the two or three screens people will live in are worth their weight.
Who should write it
Whoever is going to build it, sitting with whoever is going to use it. A specification written entirely by the client tends to describe the current system with its faults preserved. One written entirely by the developer tends to miss the exceptions that make the business work.
It should also be short enough that people read it. Twenty pages that everyone has read beats a hundred that nobody has.
The test
A good specification can be handed to a developer who has never met you, and they can produce a quote within twenty per cent of anyone else’s. If two quotes for the same document differ by a factor of three, the document is not finished.