How to Write a Software Requirements Document (With a Template Outline)
How to write a software requirements document developers can quote and build from: what to include, what to leave out, and a template outline you can copy.
Written by Ing. Hlib Yarovyi, Founder
A good software requirements document describes the problem, the users, the main flows, each feature with a way to check it works, the data and integrations, the non-functional constraints, and a clear list of what is out of scope. It does not describe the code. The test of a good one is simple: send it to two competent vendors and they should quote roughly the same product. If one quotes a weekend project and the other a six-month build, your document is leaving the important decisions to them.
We read a lot of requirements before quoting MVPs and custom software. The weak ones are rarely too short. They are vague in the expensive places and detailed in the cheap ones: three pages about the colour of buttons, one line that says “integrates with our CRM”. This guide shows how to write one that a team can estimate, build and test from, plus the outline we ask clients to fill in before a scoping call.
Why the document decides your price
Every estimate is a guess about the unknown. Developers price uncertainty in one of two ways: they pad the estimate, or they bill by the hour and let you carry the risk. A clear document reduces both.
It also protects you later. When a feature is disputed mid-project, the conversation goes to the document. “It says users can export reports” is a weak position if nobody wrote which reports, which format and for which roles. If you plan to work on a fixed price rather than time and materials, the written scope effectively becomes the contract, so its quality is directly your financial risk.
What to write before any feature list
Most people start with features. Start with the problem instead, because it is the thing that lets a developer say “you do not need that”.
The problem in one paragraph
Who has the problem, what they do today, and what it costs them. “Our sales team re-types orders from email into the ERP, around 300 a week, and errors cost us refunds” is a problem. “We need a modern portal” is not.
What success looks like
Two or three outcomes you can check after launch. Fewer manual steps, a conversion rate, a number of paying pilot customers, time to process an order. These outcomes help the team rank features when the budget gets tight, and it always does.
The users and their roles
List every type of user and what each can see and do. Roles drive more cost than most founders expect: every role multiplies screens, permissions and test cases.
| Role | Can see | Can do | Notes |
|---|---|---|---|
| Customer | Own orders and invoices | Place orders, download invoices | Signs up by invitation only |
| Account manager | Their customers’ orders | Edit orders, issue credit notes | Up to 20 users |
| Admin | Everything | Manage users, prices, settings | Two people, need audit log |
A table like this answers questions the developer would otherwise ask in week four.
Describe flows, not just features
A feature list says what exists. A flow says how someone gets value from it. Write the three to seven journeys that make the product worth paying for, step by step:
- A customer receives an invitation email and sets a password.
- They search the catalogue by product code or name.
- They add items, see their negotiated price and delivery date.
- They submit the order, which appears in the ERP within one minute.
- They get a confirmation email with a PDF.
Each step hides questions: what happens if the invitation expires, if the product is out of stock, if the ERP is down. Writing flows forces those questions early, when answering them is free.
Simple sketches help more than long prose. Photos of whiteboard drawings or rough boxes in any tool are fine. Polished designs are not required for a quote, but a list of screens is.
Write features with acceptance criteria
For each feature, add how you will check it works. This turns opinions into tests.
Weak: “Users can reset their password.”
Strong: “A user can request a reset link from the login page. The link is valid for 60 minutes and works once. After a reset, all other sessions are signed out. If the email is not registered, the page shows the same message as when it is, so nobody can probe for accounts.”
The strong version is longer, but every sentence removes a guess. You do not need this depth for every small feature. You need it for anything involving money, permissions, data deletion, or integrations with other systems.
Prioritise as you go. A simple label per feature works: must have for launch, should have, later. If everything is a must, the team cannot help you cut scope, and the first version arrives late.
The parts people forget
These sections are missing from most documents we receive, and they are where budgets go wrong.
Data and migration
What data the system stores, where it comes from, and whether existing data must be imported. “Import our 40,000 customers from a spreadsheet with inconsistent columns” can be a week of work on its own. Say how much data, in what format, and how clean it is.
Integrations
Name every external system and what flows in each direction: payments, CRM, ERP, email, SMS, single sign-on, analytics, AI APIs. For each, note whether it has a documented API and whether you have access to a test account. An undocumented legacy system is one of the biggest sources of estimate risk.
Non-functional requirements
Qualities rather than features. They change architecture and price, so state them even if the answer is “nothing special”:
- Security and compliance: personal data, health data, payment data, GDPR, audit logs, data residency in the EU.
- Performance: expected users and peak load, acceptable page response times.
- Availability: can it go down for an hour at night, or does it need monitoring and on-call?
- Platforms: browsers, mobile web, native apps. A native app is a different project; see mobile app development if that is in play.
- Accessibility: WCAG level, especially for public sector or EU consumer products.
- Languages and currencies.
- Hosting: your cloud account, a specific region, or the vendor’s choice.
Who operates it after launch
Who fixes bugs, who updates dependencies, who watches errors at night. Software has running costs after launch; we break those down in a separate post on what software maintenance costs.
The out-of-scope list
This is the most useful page in any requirements document, and the shortest. Write what you are deliberately not building in this version: no native app, no multi-currency, no reporting beyond a CSV export, no admin roles beyond one.
It stops scope creep without arguments, because the decision was made in writing before anyone was tired. It also tells the developer where you are open to simplification.
A software requirements document template
Copy this outline, delete what does not apply, and write in plain language. Most focused products fit in 5 to 15 pages.
| Section | What to write | Typical length |
|---|---|---|
| 1. Summary | Problem, goal, who it is for, launch date if fixed | Half a page |
| 2. Success measures | Two or three checkable outcomes | A few lines |
| 3. Users and roles | Role table: see, do, how many users | Half a page |
| 4. Main flows | Three to seven journeys, step by step, with sketches | 2–5 pages |
| 5. Features | Grouped list, priority, acceptance criteria for the risky ones | 2–5 pages |
| 6. Screens | List of screens or a rough clickable sketch | One page |
| 7. Data | Main entities, data volumes, import and migration needs | Half a page |
| 8. Integrations | Each system, direction of data, API availability, test access | Half a page |
| 9. Non-functional | Security, compliance, performance, availability, platforms, languages | One page |
| 10. Operations | Hosting, ownership of accounts, support expectations after launch | Half a page |
| 11. Out of scope | What is deliberately not in this version | A few lines |
| 12. Open questions | Things you do not know yet, and who will decide | A few lines |
The last section matters. Writing “we do not know yet whether invoices are generated by us or by the ERP” is far better than pretending. An honest open question becomes an item on the scoping call. A hidden one becomes a change request.
Common mistakes
- Describing the solution instead of the need. “Use microservices and Kubernetes” in a requirements document is usually a sign someone read an article. Describe the load and the reliability you need; let the engineers pick the architecture and defend it.
- Copying a competitor feature by feature. They built those features over years for their customers. Pick the slice that proves your idea.
- Leaving permissions implicit. “Managers can edit orders” — all orders, or their team’s? Before or after shipping?
- Writing it alone and freezing it. The first version is yours. The final scope should be written together with the engineer who will build it.
- No priorities. Without them nobody can cut scope intelligently when the estimate comes back higher than the budget.
From document to quote
Once you have a draft, the next step is a scoping session with the team you are considering. Expect them to ask about edge cases, challenge features that do not serve the goal, and tell you which items drive most of the cost. A team that quotes without asking anything has not read the document carefully.
The output should be a written scope that both sides sign: features, screens, integrations, acceptance criteria for the risky parts, and an explicit out-of-scope list. That is what we quote from in MVP development: one fixed price for the agreed scope, and if our estimate is wrong, the extra hours are our cost. Changes you ask for later are quoted separately first.
If you want to check the size of the budget before you write anything, our MVP development cost guide and web app development cost guide show market ranges and what moves the number. And if you want a sharper checklist for cutting the first version down, read how to scope an MVP.
The short version
- Start with the problem, the success measures and the roles, not the features.
- Write flows step by step; they reveal the questions features hide.
- Add acceptance criteria wherever money, permissions or data are involved.
- Never skip data migration, integrations and non-functional requirements.
- Keep an out-of-scope list and an open-questions list.
- Review the draft with the engineer who will build it, then freeze a signed scope.
FAQ
What is a software requirements document?
It is a written description of what a piece of software must do, who uses it, what data it handles and which constraints it must respect. Its job is to let a development team estimate, build and test the product without guessing. It describes the problem and the expected behaviour, not the code.
How long should a software requirements document be?
Long enough that two vendors would quote the same thing. For a focused MVP that is often 5 to 15 pages including user flows and a list of screens. Hundred-page specifications usually hide the important decisions under boilerplate and go out of date before the first release.
What is the difference between functional and non-functional requirements?
Functional requirements describe behaviour, for example "an admin can refund an order". Non-functional requirements describe qualities, such as performance, security, availability, accessibility, data residency and browser support. Both affect the price, and the non-functional ones are the ones people forget.
Should I write requirements myself or let the developer do it?
Write the first version yourself, because only you know the business. Then do a scoping session with the engineer who will build it. A good team turns your document into a precise scope, asks the uncomfortable questions and points out what is expensive. Treat the result as a shared document, not a contract you throw over the wall.
Do agile teams still need a requirements document?
Yes, just a lighter one. Agile changes how often requirements are revisited, not whether they exist. Even a fixed-price MVP built in weekly iterations starts from a written scope that says what is in, what is out and how you will know each feature is done.
Can I use a template for a software requirements specification?
Yes, a template keeps you from forgetting whole areas such as roles, integrations or data migration. Use it as a checklist, delete sections that do not apply, and write in plain language. The outline in this article is the one we ask clients to fill in before a scoping call.