How to write a software specification: a template, worked examples and what to leave out

What a specification is for

A specification has three jobs. It lets every supplier plan against the same thing, so you can compare approaches. It becomes the baseline for scope, so both sides know what is in and what is a change. And it forces your own team to agree what they want before anyone writes code, which is the easiest moment to change your mind.

It is not a design document or a contract, although it usually ends up attached to one.

The National Audit Office, reviewing 25 years of government IT, found a consistent pattern of underperformance, often because programmes were "not being sufficiently thought through before key decisions on technology solutions are made". Our guide to why software projects fail covers the rest of the evidence.

How long and how detailed it should be

Length should follow risk and complexity, not a template. These are rough guides from writing and reading specifications, not hard rules.

Time to write means elapsed time with a few hours a week from the people who know the process. The biggest delay is usually waiting for decisions.

The specification template, section by section

Use this outline. Not every project needs every heading at the same depth, but every heading should have at least a sentence, even if that sentence is "not applicable, because...". A blank section is where surprises hide.

The sections people skip most often are 4 and 13. The current process shows where the real complexity is: the exceptions and the spreadsheet someone keeps on the side. The out of scope list stops arguments later about what was promised.

How to write user stories

A user story describes one thing one type of user needs to do, and why. The standard form is:

As a [type of user], I want [to do something], so that [I get some outcome].

The "so that" part matters most. It tells the developer what problem they are solving, which often points to a simpler way of doing it than the one you had in mind. Here are stories for the hypothetical field service firm from the template above:

1. As an office scheduler, I want to drag a job onto an engineer's day, so that I can rebook work when someone is off sick.
2. As an engineer, I want to record parts used and take photos on my phone, so that the office does not have to call me after every job.
3. As an office manager, I want each completed job to produce a service certificate and email it to the customer, so that the paperwork goes out the same day.
4. As a customer, I want a text the day before with a two hour arrival window, so that I do not wait in all day.

Keep each story small enough to build and test in a few days. "As a manager, I want reporting" is a heading, not a story.

Acceptance criteria: examples that remove ambiguity

Acceptance criteria are the tests that prove a story is done. Without them, "done" means whatever the developer thought it meant. The most useful format is Given, When, Then, because it forces you to state the starting situation, the action and the result.

Worked example: service certificate by email

Story: As an office manager, I want each completed job to produce a service certificate and email it to the customer, so that the paperwork goes out the same day.

• Given a job is marked complete with every safety check recorded, when the engineer submits it, then a PDF certificate is created within 5 minutes and emailed to the customer address on the job.
• Given the customer has no email address on file, when the certificate is created, then it is queued for posting and appears on the office exceptions list.
• Given an appliance failed a safety check, when the job is submitted, then the certificate shows the failure clearly and the office manager is alerted the same hour.
• Given the email service is unavailable, when sending fails, then the system retries for 24 hours and the job shows on the exceptions list until it succeeds.

Notice the criteria cover the unhappy paths: missing data, failures and exceptions. That is where most of the build time goes, and it is exactly what a vague specification leaves out.

Prioritising: what must be in the first release

Give every story a priority. The most widely used method in the UK is MoSCoW: Must have, Should have, Could have and Won't have this time. The trick is being honest about Must. A Must have is something without which the system cannot go live at all, not something important.

The DSDM method that created MoSCoW recommends that Must haves take no more than 60 percent of the effort, with Should and Could making up the rest. That remaining share is your contingency. If something takes longer than planned, a Could have drops out and the launch date holds. If everything is a Must, there is nothing to give, and either the date or the scope moves.

A practical test: if the release went live without this story, could the team still do the work, even with a workaround? If yes, it is not a Must.

Data, integrations and non-functional requirements

These sections shape the design and the timeline more than the features do. Specific numbers help a supplier more than long descriptions.

• Volumes: how many users, records and transactions, today and in three years. "About 120 jobs a day, 400 in peak season" changes the design. "Lots of jobs" does not.
• Data migration: where the existing data lives (Excel, Access, an old CRM), how much there is and how clean it is. Migrating 10 years of messy history can take as long as building a feature.
• Integrations: name the product and the edition, for example "HubSpot Sales Hub" or "Sage 200 on premises". Say which direction data flows and how fresh it must be. A nightly sync is far simpler to build and run than real time. Our integration service page explains what makes one hard.
• Availability: the hours it must work and what happens if it is down for an hour. "Office hours, Monday to Saturday" and "24/7 because customers book online" are very different builds.
• Devices and accessibility: phones, tablets, desktop, which browsers, whether engineers work offline in basements, and whether public facing parts must meet WCAG 2.2 AA.

If you do not know an answer, write it down as an open question. That is far better than leaving it out, because the supplier will make an assumption and you will not see it until late in the build.

Security, data protection and reporting

Security requirements belong in the specification, not in a conversation after launch. State who can see what, by role, and whether you need:

• Single sign-on with Microsoft 365 or Google Workspace.
• Multi-factor authentication for all staff, or only for admin users.
• An audit log of who changed what, and how long it is kept.
• A penetration test by an independent tester before launch.
• Hosting in a UK or EU region, in your own company's account.

For UK GDPR, list the personal data the system will hold, why you hold it, how long each type is kept and how people can ask for their data or have it deleted. If you are unsure of any of that, the Information Commissioner's Office publishes plain guidance for organisations. Our security page shows how we handle these points on every project.

Reporting is the other section people leave vague. "Management reports" tells a developer nothing. Write down the questions managers ask and how often, for example "jobs overdue by more than 48 hours, daily". Each one becomes a story with its own acceptance criteria.

What to leave out of a software specification

Overspecifying does as much harm as underspecifying: it ties the developer to your first idea and buries the important requirements. Leave out:

• Screen designs and pixel layouts. Rough sketches of what a user needs to see are useful. Finished mock ups made in PowerPoint are not, because the designer will redo them properly.
• Database tables and field lists. Describe the information you need to record and why. Let the developer design the structure.
• Technology choices, unless they are real constraints. "Must run on our Microsoft Azure tenancy" is a constraint. "Should use React" is usually a preference picked up from an article.
• Every possible future feature. Put phase two ideas in a separate parking list. Suppliers will otherwise plan for them, or worse, design around them.
• Legal terms and contract clauses. These belong in the contract. Our guide to the software development contract covers what to put there.

Mistakes we see most often

An hour sitting with the people who do the work usually turns up more exceptions than a week of meetings.

From specification to a delivery plan

There are two routes. You can write the specification yourself and send it to three suppliers, asking each for the team, the effort per feature and a timeline in weeks, not just an end date. Our guide to choosing a software development company lists the other questions to ask.

Or you can write it with a supplier. That is what a discovery phase is: two to four weeks of workshops with your team and a review of your current systems and data, ending in a written specification, a prioritised backlog, a clickable prototype of the key screens and a delivery plan in weeks. You own the specification either way, so you can take it to another team. A typical plan that comes out of discovery looks like this:

Because every Must have story has acceptance criteria, each sprint demo is a check against the specification rather than a matter of opinion. You can see the full rhythm on our how we work page.

Checklist before you send it out

1. Every user type is listed with a rough number of people.
2. The current process is written down, including the workarounds.
3. Every requirement is a user story with a "so that".
4. Every Must have story has acceptance criteria, including what happens when things go wrong.
5. Must haves are no more than about 60 percent of the list by effort.
6. Every integration names the product, the edition and the direction of data.
7. Security, availability, devices and accessibility are stated.
8. Where personal data will be stored, and for how long, is stated.
9. There is a clear out of scope list.
10. Someone who does the work every day has read it and agrees.

The last point matters most. A specification the people doing the work have not read describes the process as managers think it runs, not as it actually does.

Questions