Almost every troubled project we have been asked to rescue was mis-specified rather than mis-coded. The engineering was fine; it was engineering for the wrong thing. A requirements document is the cheapest insurance in software, because it is the only stage where changing your mind costs a conversation instead of a sprint. Here is how to write one that a development team can genuinely quote and build from — with a template you can copy at the end.
The short version
- Write requirements as user outcomes with acceptance criteria, not as a feature wish-list. "User can reset password" is not a requirement; the seven states around it are.
- The out-of-scope section is the most valuable part of the document. It prevents more disputes than the in-scope section.
- Specify roles and permissions first. Everything else — screens, reports, cost — follows from the role matrix.
- Include non-functional requirements (load, response time, browsers, devices, uptime, data residency). These change architecture and therefore price.
- A good SRS for a mid-size project is 12–25 pages. A 90-page document nobody reads is worse than a 12-page one everybody does.
Why the document matters more than the contract
Contracts allocate blame after something goes wrong. Requirements documents prevent it going wrong. When a client and a studio disagree six weeks into a build, the disagreement is nearly always about something both parties assumed was obvious and neither wrote down.
A real example. A brief said the system should "let managers approve leave requests". Reasonable sentence. It did not say whether approval could be delegated while a manager was on leave, whether a rejected request could be resubmitted, whether HR could override a manager, whether partial-day leave existed, or whether approval triggered a payroll adjustment. Those five unwritten questions were eleven developer-days and a difficult conversation.
Every sentence in a brief that contains "simply", "just", or "obviously" is a sentence that will cost money.
The structure that works
Formal standards exist for this. Most are too heavy for commercial projects. The structure below is what we ask clients for, and what we produce ourselves during a paid discovery phase.
1. Purpose and success criteria
Two or three paragraphs: what problem this solves, who has the problem, and how you will know in six months whether it worked. Make the success criteria measurable — "reduce order entry time from 8 minutes to under 2", "handle 400 concurrent users during registration week", "eliminate the weekly manual Excel reconciliation". Teams make better technical decisions when they know what they are optimising for.
2. Users and roles
List every distinct type of user, what they can see, and what they can do. Do this as a table. It is the highest-value page in the whole document, because role count drives cost more than screen count does.
| Role | Can view | Can create/edit | Can approve/delete | Notes |
|---|---|---|---|---|
| Sales agent | Own leads only | Own leads, quotes | None | Cannot see pricing margin |
| Branch manager | All leads in branch | Reassign leads | Approve discounts <10% | Monthly branch report |
| Finance | All invoices | Payments, credit notes | Void invoice | Needs export to accounting |
| Owner | Everything | Nothing | Nothing | Read-only dashboard |
3. Functional requirements, written as outcomes
The format that survives contact with a development team is: As a [role], I need to [action], so that [outcome] — followed by explicit acceptance criteria. The user story tells the developer why; the acceptance criteria tell them when they are finished.
Example, done properly
Story: As a sales agent, I need to convert a lead into a customer so that I can raise an invoice against it.
Acceptance criteria:
1. Conversion requires a phone number and at least one address on the lead.
2. On conversion the lead status becomes "Converted" and becomes read-only.
3. All notes, files and call history transfer to the customer record.
4. If a customer with the same phone number already exists, the agent is shown a merge prompt and cannot create a duplicate.
5. Conversion is recorded in the audit log with user and timestamp.
6. A converted lead cannot be reverted by an agent; only a branch manager can.
Notice that criterion 4 and criterion 6 are the expensive ones, and neither appears in the original sentence. That is the entire point of the exercise.
4. The states nobody writes down
For every screen that loads or submits data, decide four things. If your document answers these for each major screen, you have eliminated most of the ambiguity in the project:
- Empty state. What does a brand-new user with no data see? This is your onboarding, and it is usually forgotten until the week before launch.
- Loading state. Spinner, skeleton, or optimistic update?
- Error state. What happens on a failed request, a validation error, a lost connection? What exactly does the user read?
- Permission state. What does a user who lacks access see — a hidden menu item, or a "no access" message?
5. Non-functional requirements
These are the requirements that change the architecture, which is why omitting them is expensive. Be specific:
- Scale: expected users, concurrent peak, records after three years, file storage volume.
- Performance: acceptable page and API response times; which screens must feel instant.
- Availability: is overnight downtime acceptable, or is this a 24/7 system? This decides your hosting bill — see our hosting comparison.
- Devices and browsers: the real ones your users have, not the ones you wish they had. Include minimum Android version and screen size.
- Security and compliance: data residency, retention periods, audit requirements, two-factor authentication, encryption of specific fields.
- Localisation: languages, right-to-left support, currency and date formats. Retrofitting Urdu or Arabic RTL support is expensive; planning for it costs little.
- Backups and recovery: how much data you can afford to lose, and how fast you must be back up.
6. Integrations
For each external system, record: what it is, who owns credentials, whether documentation exists, whether a sandbox environment exists, and whether anyone has successfully integrated with it before. Integrations against undocumented or unstable third-party systems are the single most common source of estimate blowouts, and they need a named owner on the client side who can chase the other vendor.
7. Explicitly out of scope
Write this section even if it feels awkward. Especially if it feels awkward. List the things a reasonable reader might assume are included but are not: other languages, other platforms, data migration, content writing, SEO work, training, third-party licence costs, offline mode, a public API. Then list what is deliberately deferred to a later phase.
This section is not defensive paperwork. It is a shared understanding, and it lets both sides talk about phase two without pretending phase one failed.
8. Deliverables, milestones and acceptance
What you receive (source code, design files, deployment scripts, documentation, admin credentials), when, and who signs off. Define what "done" means for the project as a whole, and how long the post-launch warranty period is.
Seven mistakes we see constantly
- Specifying the solution instead of the problem. "Add a dropdown here" forecloses better options. Say what the user is trying to achieve and let the team propose the interface.
- No priority order. If everything is essential, nothing can be deferred when the timeline tightens — and it will tighten. Mark each requirement Must / Should / Could.
- Ignoring reporting until the end. Reports drive database design. A report requirement discovered in month three can mean restructuring how data was stored.
- Forgetting the admin side. Someone has to manage users, edit content, fix bad records and re-send failed emails. Admin tooling is routinely 20–30% of a build and routinely absent from briefs.
- No decision-maker named. If four stakeholders can each request changes and none can approve, the project has no steering. Name one person.
- Treating the document as immutable. It is a living artefact. Version it, date it, and log changes with who approved them.
- Skipping wireframes. Twenty rough wireframes eliminate more ambiguity than eighty pages of prose. They do not need to be pretty; boxes and labels on paper are enough.
The template
Copy this outline into a document and fill it in. If a section genuinely does not apply, write "not applicable" rather than deleting it — the absence is itself information for whoever quotes the work.
Software Requirements Document — outline
1. Overview — problem, audience, measurable success criteria, launch deadline and why.
2. Users & roles — role/permission table.
3. Scope summary — one-paragraph description of what is being built.
4. Functional requirements — grouped by module; each with user story, acceptance criteria, priority (Must/Should/Could).
5. Screens — list with purpose, and empty/loading/error/permission states.
6. Business rules — calculations, tax, discount logic, approval thresholds, numbering formats, working hours.
7. Notifications — every email, SMS and push: trigger, recipient, channel, content.
8. Reports & exports — each report, its filters, its columns, its format.
9. Integrations — system, owner, credentials, docs, sandbox availability.
10. Non-functional requirements — scale, performance, availability, devices, security, localisation, backups.
11. Data migration — sources, volume, quality, who cleans it.
12. Out of scope — explicit exclusions and deferred phases.
13. Deliverables & milestones — artefacts, dates, acceptance process, warranty.
14. Open questions — with an owner and a date needed against each.
15. Change log — version, date, change, approver.
How much effort is this worth?
For a project under PKR 500,000, two to four focused hours and a five-page document is proportionate. For a PKR 3M platform, a week of your time — or a paid discovery phase with your development partner — is not just proportionate, it is the highest-return week in the project.
Our own rule: if the document takes more than 5% of the project budget to produce, it is too detailed. If it takes less than 1%, it is too thin. Section 14 — open questions — is the one people skip and the one that matters most; an honest list of what you do not yet know is far more useful to a development team than a confident answer that turns out to be wrong.
If you would rather not write it alone, that is what a discovery phase is for. We run them as a fixed-price piece of work that ends with wireframes, a technical approach and a firm build quote — and the document is yours regardless of whether you then build with us. See our cost breakdown for how discovery fits into a budget, or start a conversation.