How to write a software requirements specification developers understand

A good software requirements document describes the product's goals, user roles and the scenarios users go through — with acceptance criteria for each — rather than screens and buttons. Both the client and the developers can understand it, and it is enough to estimate time and budget. It is best written together with the vendor: you know the business, the team knows the technical constraints.

Below is the structure we use, an example of a well-described scenario and the mistakes that make even a hundred-page document useless.

Why do you need a requirements document?

You need a requirements document so that the client and the team share the same understanding of what will be built and can verify the result. Without one, estimates turn into guesswork and acceptance turns into an argument about what was "meant".

A specification does three jobs:

• estimation — a list of scenarios lets the team calculate the work instead of guessing a number;
• acceptance — every scenario has criteria that show whether it is done;
• project memory — six months later a new developer or a new vendor can see why the system works the way it does.

It is just as important what a specification does not do: it does not replace conversation. A document that was written, handed over and never opened again is out of date by the first week of development.

What does a good specification contain?

A good specification contains the business goal, user roles, scenarios with acceptance criteria, data and integration requirements, and non-functional requirements. Each section answers its own question, and an unanswered question should be recorded as an open question, not left as a gap.

Section	Question it answers	Example
Goal and metrics	Why the product exists and how to tell it works	Cut request processing time to 1 hour
Roles	Who uses the system and what they may do	Customer, manager, administrator
Scenarios	What a user does from start to finish	Place an order, return an item
Data	Which entities are stored and how they relate	Order, line item, customer, payment
Integrations	Which external systems exchange data	Payment provider, CRM, delivery service
Non-functional requirements	Speed, load, security, languages	Catalogue page loads in under 1 second
Out of scope	What this version definitely will not include	Mobile app, loyalty programme

The "Out of scope" section is the most underrated, yet it prevents the most disputes. If the document says the partner portal is not in the first release, nobody expects to see it at acceptance.

Photo: Unsplash

How do you describe scenarios so developers understand them?

Describe a scenario as a sequence of user steps and system responses with explicit success conditions and failure cases. Developers need to know not only what should happen but also what happens when something goes wrong: the alternative paths take up most of the work.

A scenario template

Scenario: Customer pays for an order by card
Role: customer (signed in)
Precondition: the cart contains at least one item in stock

Main path:
  1. Customer clicks "Checkout"
  2. System shows the summary: items, delivery, total
  3. Customer chooses card payment
  4. System redirects to the payment provider's page
  5. After payment the order becomes "Paid" and the customer gets an email

Alternatives:
  3a. An item sold out during checkout — show which one and remove it from the total
  5a. Payment declined — return to step 3, order stays "Awaiting payment"
  5b. The bank sends the confirmation twice — the order is not paid twice

Acceptance criteria:
  - a paid order appears in the manager's admin panel within a minute
  - a repeated bank notification changes nothing and sends no second email

This format is readable without a technical background and still gives developers everything they need to estimate the work and write tests.

Who should write the specification?

The client and the development team should write it together, usually through a business analyst or product manager. The client brings knowledge of the business and its users; the team brings an understanding of what is hard, what is expensive and what can be done more simply.

How the roles usually split:

1. The client states the goal and describes users and current processes.
2. The analyst runs interviews, collects scenarios and looks for contradictions and gaps.
3. The tech lead estimates the scenarios, suggests simplifications and records technical constraints.
4. The designer builds prototypes of key screens from the scenarios.
5. The client reads the result and confirms it is what they need.

A first estimate does not require a full specification — a product description and the main scenarios are enough, as we explained in what goes into an MVP estimate. The detailed document is assembled during discovery.

What mistakes make a specification useless?

A specification becomes useless when it describes a solution instead of a problem, skips the alternative scenarios or has no acceptance criteria. Length does not help: a hundred-page document can still fail to answer the key question — what counts as done.

The most common mistakes:

• "Build it like the competitor" without saying what problem the feature solves for you.
• Vague requirements: "user-friendly interface", "fast", "reliable" — with no numbers or conditions.
• Happy path only: nothing about failed payments, empty lists or lost connections.
• Technical solutions dictated by the client: "use microservices" instead of "handle 500 orders an hour".
• A document nobody updates: decisions from calls stay in chat, and the specification describes a system that no longer exists.

How to check the specification before sending it to a vendor

Read each scenario and ask: could I verify from this text that the work is done? If the answer is "no" or "we'll see", the scenario lacks acceptance criteria. The second test: give the document to someone who was not in the discussions and ask them to explain what the product does.

In short

• A specification describes goals, roles and scenarios with acceptance criteria, not screens.
• Alternative paths matter more than the happy path — that is where most of the work is.
• The "Out of scope" section prevents the most disputes at acceptance.
• Write it together with the development team and keep it updated as the project moves.
• A product description and the main scenarios are enough for a first estimate.