A software requirements document is the written record of what a system must do, how it must behave, and the limits it must work within, written as numbered statements that someone can test. Learning how to write a software requirements document properly comes down to one habit: every requirement gets an ID, an owner, and a check that proves it was met. Get that right and the arguments in the kickoff meeting turn into decisions instead of rewrites.
The format below works for a two-week internal tool and for a public-sector procurement. I drafted the first version in a day once the scope was already agreed, and the slow weeks were always spent chasing who could sign off, never writing prose.
Table of Contents
- What You Need
- Step-by-Step: How to Write a Software Requirements Document
- Step 1: Define the Problem and Project Scope
- Step 2: Identify Users and Stakeholders
- Step 3: Gather and Prioritize User Requirements
- Step 4: Write Functional Requirements
- Step 5: Document Non-Functional Requirements
- Step 6: Define Data, Integrations, and Interfaces
- Step 7: How to Write Acceptance Criteria and Traceability
- Step 8: Review, Approve, and Maintain the Document
- Common Mistakes
- Frequently Asked Questions
- What is a software requirements document and who writes it?
- What is the difference between an SRD and an SRS?
- How long should a software requirements document be?
- Do agile teams still need a requirements document?
- What makes a requirement good?
- Conclusion
What You Need
You can start drafting with less than you think, but you cannot skip any of these inputs. Missing information does not stop the document, it just moves into the assumptions section where it is visible.
- The problem statement — what is broken or missing today, in plain language, with no solution named.
- A stakeholder list with roles — who supplies funding, who approves, who operates the thing on day one, and who reviews it.
- User research or workflow notes — interviews, support tickets, observation, the way people do the job right now.
- An integration inventory — every other system, vendor or data feed the software must touch, with an owner on each side.
- Constraints and legal duties — privacy law, records retention, accessibility standard, procurement rules, existing contracts.
- Success measures — the numbers that decide whether the project worked, agreed before design starts.
- Approval rules — who signs, and whether one signature is enough or four departments must agree.
When information is incomplete, write it down as an assumption with an owner and a date. “The transit agency will expose a real-time delay feed by March” is useful; leaving it unwritten means someone assumes it later without ever being asked.
Step-by-Step: How to Write a Software Requirements Document
The process below runs in eight steps and follows one rule: the finished document is traceable from business goal to user need to requirement to acceptance criterion to test evidence. If you can follow one line of text from the reason the project exists to the test that proves a feature works, the document is doing its job.
Step 1: Define the Problem and Project Scope
Write the problem before the solution. Two sentences: what breaks today, and what would be different for a user if this worked. If a sentence could have been written by someone pitching a product, rewrite it as an observation about the current state.
Then draw the boundary explicitly. List what is in scope, what is out of scope, and what depends on another team. The out-of-scope list is the most-read section in the whole document, because it is where scope creep goes to die.
A first question readers always have is which document they are actually writing, so settle that now.
| Document | Answers | Typical owner | Depth |
|---|---|---|---|
| Business requirements document (BRD) | Why the business is funding this and what outcome it buys | Business analyst or sponsor | High level, no system detail |
| Product requirements document (PRD) | What the product should do for users and how it will be measured | Product manager or owner | Feature level, market and roadmap context |
| Software requirements document (SRD) or software requirements specification (SRS) | What the system must do, the interfaces, the constraints and the tests | Business or systems analyst with engineering input | Detailed, testable, per requirement ID |
| Functional requirements document (FRD) | Only the behaviour and business rules of the system | Analyst or developer | Subset of an SRS, behaviour only |
These names overlap in the wild. SRD and SRS are frequently the same document with two labels, which is why the argument about which one to write usually wastes an afternoon. If your project has a funded business outcome and a technical system behind it, you usually want a BRD feeding an SRS, and one SRS is enough.
Step 2: Identify Users and Stakeholders
Name the people who will use, administer, approve, fund and be affected by the system. For each one, capture what they are trying to achieve, what they need to see, and what they must never be able to do.
Separate primary users from secondary ones. A resident reporting a bus disruption is primary; the transit operations manager watching aggregated patterns across a district is secondary; the finance officer reconciling fees is a stakeholder who never logs in but whose rules shape the screens.
Resolve conflicting priorities before you write a single requirement. Two groups wanting opposite things is a decision for the sponsor, not an ambiguity for the developer. Record who decided and why, because that decision is what you will be asked to defend at review.
Step 3: Gather and Prioritize User Requirements
Convert research into requirement statements rather than notes. Each statement says who needs what, and why. Examples from a transit disruption tool: “A resident needs to report a delayed bus in under 30 seconds from the map screen” and “A city manager needs weekly disruption counts by route without exporting data first.”
Prioritise before you detail anything. MoSCoW is enough for most teams: Must have, Should have, Could have, Will not have. Anything in the Will not column gets written down deliberately, because that is the list you will be asked about when a stakeholder asks for it three months in.
Keep a source note on each statement. Six interviews and a policy document that mentions the target are not the same weight, and knowing which is which saves an awkward argument later.
Step 4: Write Functional Requirements
Write what the system must do as one testable statement per line, with an ID, and use the word “shall” for mandatory behaviour. A functional requirement names the actor, the action, the condition, and the response.
REQ-RPT-003: The system shall allow a signed-in resident to submit a disruption report with route, direction, location and photo from the map screen, and shall confirm receipt on screen within 2 seconds of submission.
Cover permissions, notifications, data entry rules, reporting, search, integrations and the exceptions. The exception line is the one teams skip and then regret: what happens on a duplicate submission, a failed upload, an expired session or a feed that returns nothing.
Do not describe screens or database design in this section. The document answers what must be true, and design belongs to the team that will choose how.
Step 5: Document Non-Functional Requirements
Non-functional requirements are the quality attributes the system must hold, and they are worthless without a number attached. Replace every adjective with a measurable threshold that someone could fail.
- Performance: 95% of disruption report submissions confirmed within 2 seconds under 500 concurrent users.
- Availability: 99.5% monthly, excluding scheduled maintenance announced 48 hours ahead.
- Accessibility: WCAG 2.2 AA for all public-facing screens, verified by audit before launch.
- Privacy: only the fields needed to process a report are collected; location history is never retained.
- Recovery: a failed submission is preserved locally and retried automatically once connectivity returns.
- Auditability: every change to a report record is written to an append-only log retained for seven years.
Privacy, accessibility and audit rules are not optional extras in public-sector work. A procurement review will ask for the standard you are measuring against, so name it.
Step 6: Define Data, Integrations, and Interfaces
Map each data entity: its fields, where each field comes from, who owns it, how it is validated, how long it is kept and whether a person consented to its use. For every interface, name the system, the direction of data flow, the owner on the other side and the failure behaviour.
Where a dependency is unconfirmed, say so. “The agency has not yet committed to exposing the stop-level delay feed” is an honest line that protects the schedule; promising a feed you have never seen in a data dictionary is not.
Include the interfaces people forget: email and SMS gateways, payment services, identity providers, analytics, and the export formats auditors ask for a year later.
Step 7: How to Write Acceptance Criteria and Traceability
Every functional requirement needs an acceptance criterion that a tester, a designer and a stakeholder would all accept as proof. The simplest reliable form is Given, When, Then.
Given a signed-in resident on the map screen, when they submit a disruption report with a photo, then the report appears in the operations queue with the photo attached and the resident sees a confirmation reference within 2 seconds.
Then link the requirement forward. A single traceability row ties a requirement to the user story that delivers it, the test case that verifies it and the evidence stored at sign-off. One row looks like this:
| Requirement ID | User story | Test case | Evidence at sign-off |
|---|---|---|---|
| REQ-RPT-003 | US-014 Resident reports a disruption | TC-221 Submission with photo | Test run log dated 12 May, screenshot of queue entry |
A traceable requirement is what makes the difference between “we built it” and “it was agreed” meeting at the end of the project. Teams that skip the matrix find out about the gap at handover, which is the worst possible moment.
Step 8: Review, Approve, and Maintain the Document
Run structured review rather than a single read-through. Send the draft to product, engineering, legal, accessibility, security and operations, plus two or three representative users, and give each a week with named questions to answer.
Record what changed and why in a decision log, then baseline the approved version with a date and an approver list. After sign-off, every change goes through a short change-control step: what changed, why, what it affects, who approved it.
Set the triggers that send you back to the document rather than into the code. A new regulation, a partner API that changes, a missed success measure, a request that adds a user group, or a re-baseline after a funding change all qualify. Knowing how to write a software requirements document is half the job; keeping the approved one alive is the other half. A document nobody reopens is a document nobody trusts.
Common Mistakes
Most requirement failures are not writing failures. They are ordinary habits that look productive and produce documents nobody can test. Here are the ones I see most, with the fix that works.
- Writing the solution instead of the need. “Add a Redis cache” is a decision; “search results return within 1 second for a 50,000-record dataset” is a requirement. Write the outcome and let the team choose the mechanism.
- Vague language. “The system should be fast, secure and easy to use” cannot fail and therefore cannot be tested. Put a number on every quality attribute.
- Omitting exceptions. Duplicates, timeouts, empty feeds, lost connectivity and expired sessions are where projects actually break. Give each one a requirement ID.
- Filling the document with technical design. Diagrams, database schemas and stack choices age badly and cause arguments that belong in a design review. Keep the SRS on what must be true.
- No prioritisation. Everything marked essential means nothing is. Use MoSCoW and keep the Will not list visible.
- Ignoring privacy and accessibility. Both are cheap to specify up front and expensive to retrofit. Reference the standard and the retention period.
- Treating it as permanent. The version file called SRS_Final_v3_FINAL is the warning sign. One living document with a change log beats five near-identical copies.
Before anyone signs, run a short final check: every requirement has an ID, an owner and a priority; every functional requirement has acceptance criteria; every non-functional requirement has a number; every requirement maps to a test; the out-of-scope list has been read aloud to the sponsor; and every assumption has a named person to confirm it.
Frequently Asked Questions
What is a software requirements document and who writes it?
A software requirements document records what a system must do, how it must behave and the constraints it works under, as numbered statements that can be tested. Business analysts and systems analysts usually write it, with product managers or owners providing the goals and priorities. Engineers review it for feasibility, and the sponsor signs it off so the scope becomes agreed before development starts.
What is the difference between an SRD and an SRS?
In practice, very little. Both acronyms expand to software requirements document and software requirements specification, and most organisations use the names interchangeably for the same artefact. What matters is the content, not the label: a genuine specification lists functional and non-functional requirements, interfaces, constraints and acceptance criteria. If yours lacks requirement IDs and testable acceptance criteria, the name on the cover will not fix it.
How long should a software requirements document be?
Long enough to be testable and no longer. A small internal tool often needs six to ten pages, while a public-sector system with multiple integrations runs to fifty or more. Length follows the number of requirements and the number of parties that must agree. If a reader cannot find the requirement they care about in two minutes, the document needs better IDs and headings, not fewer pages.
Do agile teams still need a requirements document?
Yes, but not in the waterfall shape. Agile teams keep the purpose, scope, constraints, non-functional requirements and interfaces in a stable document, then hold the changing detail as epics and user stories in the backlog with their acceptance criteria. The document records why the work exists and what cannot be traded away; the backlog records what is being built this sprint. Teams that write nothing end up rediscovering scope every planning session.
What makes a requirement good?
A good requirement is necessary, unambiguous, complete, consistent, singular, feasible, verifiable and traceable. Necessary means no padding. Unambiguous means one reading only. Complete covers edge cases and failure handling. Singular describes one thing. Feasible fits the team and budget. Verifiable means a test could pass or fail it. Traceable means it links to the goal, story and test behind it.
Conclusion
Start with the problem, the users and the measures that say whether the work succeeded, then write requirements that someone else can test without asking you what you meant. Give each one an ID, an acceptance criterion and a link to a test. Bring the result to the people who will build it, run it and be accountable for it, get it signed, and reopen it the moment something changes.
