A specification is not a technical document. It is an agreement about what “finished” means — which is why somebody without technical knowledge can and should write it.
The rule that makes it useful: describe what must happen, not how it will be built. The “how” is the developer’s job; imposing it without reason means paying more for a worse result.
Want us to look at your spec before you send it?
Send it over and we will show you the gaps that will cost you later.
The structure of the document
Six sections. Ten pages at most — beyond twenty, nobody reads the whole thing.
| Section | What it contains |
|---|---|
| 1. Purpose | The problem and what counts as success, with numbers |
| 2. Roles | Who uses it and what each is permitted to do |
| 3. Functions | The user stories, in priority order |
| 4. Data | What is stored, where it comes from, where it goes |
| 5. Constraints | Volume, speed, devices, legal |
| 6. Out of scope | What is explicitly not included |
The sixth section is the most valuable and it is almost always missing. Anything not written as an exclusion gets assumed by somebody — and assumptions surface at delivery.
What a user story is and why it works
One sentence with three parts: who, what they want, why.
As a warehouse supervisor, I want to scan barcodes on goods-in, so that I do not enter quantities by hand.
The “why” matters most. It lets the developer propose a better solution than the one you imagined — and often a cheaper one.
How to prioritise them:
| Level | Meaning |
|---|---|
| Essential | Nothing works without it |
| Important | Must be included, but can wait for phase two |
| Desirable | If time or budget allows |
The reality check: if more than 60% are “essential”, you have not prioritised. You have written a wish list, and the first delay will force you to cut without a criterion.
How to write acceptance criteria
Every user story needs 2–4 criteria answering “how do we know it was done correctly”.
They are written as given / when / then:
Given the product exists in the system,
when the user scans the barcode,
then the product appears and one unit is added to the goods-in record.
And the critical one people forget — what happens when something goes wrong:
Given the code does not exist,
when the user scans it,
then a message appears offering to create a new product.
Half of all delivery disputes concern exactly these error scenarios. A system that works perfectly when everything goes right is not finished.
The five gaps that cost most
- Permissions per role. Who sees cost prices? Who can delete? Undefined means everybody sees everything.
- What happens to existing data. Is it migrated? Cleaned? Who checks it?
- How many concurrent users and how many records. This determines architecture; mention it later and it gets rebuilt.
- Mobile behaviour. “It should work on mobile too” is not a specification. Which screens, with which functions?
- Integrations. What it connects to, in which direction, and which system is the source of truth — see why that matters in API integration.
The third is the most expensive to fix afterwards. A system designed for 5 users does not become a system for 50 through an upgrade.
Want a specification template?
Ask us for it and we will send it with worked examples.
How detailed, realistically
| Project size | Spec length | Time to write |
|---|---|---|
| A small internal application | 3–5 pages | 1 day |
| A management system | 8–15 pages | 3–5 days |
| A platform with many roles | 15–30 pages | 1–2 weeks |
That time is not a delay — it is the cheapest phase of the project. A change in the document costs minutes; the same change after development costs days.
And one alternative worth considering: if you struggle to describe what you want, build a quick no-code prototype and use it for a month. The specification that emerges is incomparably better — see when that works in no-code and low-code.
What you do not need to write
Five things better left to your partner:
- Programming language and database, unless there is a compatibility reason.
- How the screens will be designed — describe what the user must be able to do.
- Where it will be hosted, unless you have a data location requirement.
- Technical solutions you read about somewhere and that sound right.
- A task-by-task timeline. You give a target date; the breakdown is their job.
The fourth creates more problems than it solves. Describe the problem and leave the solution to whoever will support it.
Frequently asked questions
I’m not technical. Can I write this?
Yes, and you are the right person. You know the work; the developer knows the implementation.
What if I change my mind along the way?
Normal. Which is why the contract sets out a change process — see the points in outsourcing software development.
Do I need screen designs?
They help a great deal, even rough ones on paper. Not compulsory, but they reduce misunderstandings.
Who should approve it?
One person on your side, by name, and at least one of the people who will use it daily.
If I buy off-the-shelf software, do I still need this?
In shorter form, as a requirements list for evaluation. The comparison of the two routes is in custom software vs off-the-shelf.
The first step
Write five user stories for the most important functions, in the form “as a [role], I want [what], so that [why]”.
Give them to somebody who will use the system and ask what is missing. That one conversation will save you more than the entire testing phase.
Next step
Book a free 30-minute call with the team at The Dev Alley. We will read your spec and show you the gaps.