How to Write a Software Requirements Document (With a Section-by-Section Outline)
A practical, section-by-section outline for a software requirements document, with examples that both clients and developers can understand and use.
A software requirements document describes what a system must do and how well it must do it, so clients and developers agree before building. Include the purpose and scope, users, functional requirements, non-functional requirements such as security and performance, integrations, constraints, assumptions and acceptance criteria. Write each requirement so it is clear, specific and testable.
Photo: Unsplash
On this page
Most software projects that go wrong don’t fail because of bad code. They fail because the people paying for the software and the people building it had different pictures in their heads. A good software requirements document closes that gap before it gets expensive.
This guide walks through how to write one, section by section, with examples you can adapt. It works whether you’re a business owner briefing an agency, a product manager working with an internal team or a developer writing up what a client asked for.
What a software requirements document is
A software requirements document, often called an SRS (software requirements specification), describes what a system must do and the qualities it must have. It’s the shared reference that clients, designers, developers and testers all work from.
There’s an international standard behind the concept. ISO/IEC/IEEE 29148, currently in its 2018 edition, covers requirements engineering for systems and software, including the content of requirements documents. It superseded the older IEEE 830-1998 recommended practice that many SRS templates are still based on. You don’t need to buy the standard to write a good document, but it’s worth knowing that the structure below follows long-established practice.
A requirements document answers “what” and “how well,” not “how.” It should say “Customers can reset their password by email,” not “Use library X to send a token.” Design decisions come later.
Key takeaway: If a developer and a client read the same requirement and picture different results, the requirement isn’t finished. Clarity now is far cheaper than rework later.
Do you still need one with agile?
Yes, though it may look different. In waterfall projects, the requirements document is usually detailed and signed off before design starts. In agile projects, requirements often live as a product backlog of user stories that evolve over time. (See agile vs waterfall for how the 2 methods differ.)
Even agile teams benefit from a short, living requirements document covering vision, scope, users, non-functional requirements and constraints. Those big-picture items don’t fit neatly into individual stories, and they’re the ones most often forgotten.
| Project type | Recommended format |
|---|---|
| Fixed-price contract with an agency | Detailed SRS, signed off before build |
| Regulated software such as health or finance | Detailed SRS with traceability to tests |
| Internal agile product team | Lightweight requirements doc plus backlog of user stories |
| MVP or prototype | 1 to 3 page brief with core user stories and success metrics |
The section-by-section outline
Here’s a structure that works for most business software. Adjust the depth to your project’s size and risk.
1. Introduction and purpose
Explain why the software exists and what problem it solves, in 1 or 2 paragraphs.
Example: “This document defines requirements for a web-based booking system that lets clients of a 3-location physical therapy practice book, change and cancel appointments online, reducing phone volume at the front desk.”
2. Scope
State what’s in and, just as important, what’s out.
Example: - In scope: online booking, cancellations, automated reminders, staff calendar view. - Out of scope: billing, insurance verification, telehealth video.
A clear out-of-scope list prevents most “I assumed that was included” arguments.
3. Definitions and glossary
List terms that could be misunderstood: “provider,” “location,” “no-show,” “active client.” Agreeing on vocabulary prevents subtle errors in the data model.
4. Users and stakeholders
Describe each type of user, what they need and how technical they are.
| User type | Main goals | Notes |
|---|---|---|
| Client | Book and manage appointments | Mostly on phones; some older users |
| Front desk staff | View and adjust schedules | Uses desktop all day |
| Provider | See daily schedule | Needs quick mobile view |
| Practice manager | Reports and settings | Admin permissions |
5. Functional requirements
These describe what the system does. Number every requirement so it can be referenced in testing and change requests. Many teams use “must” for mandatory and “should” for desirable.
Examples: - FR-01: The system must let a client book an available appointment slot for a selected provider and location. - FR-02: The system must send a confirmation email within 5 minutes of a booking. - FR-03: The system must let a client cancel an appointment up to 24 hours before its start time. - FR-04: The system should send a text reminder 24 hours before each appointment to clients who opted in.
User stories are a friendly way to capture the same thing: “As a client, I want to reschedule online so that I don’t have to call during work hours.” Pair each story with acceptance criteria (see section 10).
6. Non-functional requirements
These describe how well the system performs. They’re the most frequently forgotten section and the source of many unpleasant surprises.
| Category | Example requirement |
|---|---|
| Performance | Booking pages load in under 2 seconds for 95% of requests under normal load |
| Availability | Service availability target of 99.9% per month, excluding scheduled maintenance |
| Security | All traffic encrypted in transit; staff accounts require multi-factor authentication |
| Privacy and compliance | Handles health information in line with HIPAA requirements |
| Accessibility | Client-facing pages meet WCAG 2.2 Level AA |
| Scalability | Supports 5 locations and 50 providers without redesign |
| Browser and device support | Latest 2 versions of major browsers; iOS and Android phones |
| Data retention | Appointment history retained for a defined period set by the practice |
Accessibility targets usually reference the W3C’s Web Content Accessibility Guidelines (WCAG) 2.2, which define 3 conformance levels: A, AA and AAA. For availability targets, our guide to SLA vs SLO vs SLI explains how to phrase them. If your software touches health data, read HIPAA compliance for software before writing this section. This is not legal advice.
For security, many teams reference the NIST Secure Software Development Framework (SP 800-218), which recommends identifying and documenting security requirements for the software you build and keeping them current throughout development.
7. Integrations and data
List every external system the software must connect to, what data flows each way and how often.
Example: “The system must sync appointments with the practice’s existing EHR every 15 minutes via the vendor’s API.” Note who owns each integration and whether API access requires a separate contract.
8. Constraints and assumptions
Constraints are fixed limits: budget, deadline, required hosting provider, required technology, legal rules.
Assumptions are things you believe are true but haven’t confirmed: “The EHR vendor’s API supports writing appointments.” Listing assumptions makes risks visible so someone can check them early.
9. Prioritization
Not everything is equally important. A simple method is MoSCoW:
- Must have: the release fails without it
- Should have: important, but there’s a workaround
- Could have: nice to have if time allows
- Won’t have this time: explicitly deferred
Prioritization makes trade-offs easier when time or budget gets tight.
10. Acceptance criteria
Acceptance criteria describe how you’ll know a requirement is met. A popular format is Given/When/Then:
Example for FR-03: - Given a client has an appointment more than 24 hours away, - when they select Cancel and confirm, - then the slot becomes available, and the client receives a cancellation email.
Clear acceptance criteria turn requirements into test cases and reduce disputes at sign-off.
11. Change process and sign-off
Describe how requirements can change after approval: who can request a change, who approves it and how cost or schedule impacts are assessed. Then list who signs off on the document.
How to write requirements that developers can build
Good requirements share a few traits:
- Specific. “Fast” isn’t a requirement. “Loads in under 2 seconds” is.
- Testable. If you can’t write a test for it, rewrite it.
- Single. 1 requirement per statement. Split “and” requirements in 2.
- Unambiguous. Avoid words like “user-friendly,” “flexible,” “robust” and “etc.”
- Necessary. Each requirement should trace back to a real business or user need.
- Free of design. Describe the outcome, not the implementation, unless there’s a real constraint.
A quick rewrite example:
| Weak | Strong |
|---|---|
| The system should be easy to use | A new client can complete a booking in 3 steps or fewer without help |
| Reports must be fast | The monthly appointment report generates in under 10 seconds for up to 10,000 appointments |
| Support mobile | All client pages are fully usable on screens 375 pixels wide and larger |
Where to start: a step-by-step process
- Interview stakeholders. Talk to the people who will use, pay for and support the software. Ask about current pain, not just desired features.
- Observe the current process. Watching someone do the job reveals requirements nobody mentions.
- Draft the outline above. Fill in purpose, scope and users first.
- Write functional requirements and user stories, numbered and prioritized.
- Add non-functional requirements using the table as a checklist.
- Review with both sides. Have a developer read for buildability and a business owner read for completeness.
- Get sign-off, then keep the document under version control and update it through the change process.
If you’re still deciding what to build first, our MVP development guide helps you cut scope, and our guide to custom software development cost shows how clearer requirements lead to more accurate quotes.
Common mistakes to avoid
- Writing a wish list with no priorities
- Skipping non-functional requirements entirely
- Describing solutions instead of needs
- Forgetting the out-of-scope list
- Leaving integration details vague
- Treating the document as finished once signed, instead of maintaining it
Requirements also feed every later stage of the software development life cycle, from design to testing. Shortcuts here often show up later as technical debt.
Conclusion
A software requirements document is the cheapest insurance a software project can buy. Define the purpose and scope, describe your users, write clear and testable functional and non-functional requirements, list integrations, constraints and assumptions, and agree on acceptance criteria and a change process. Keep it as long as your project needs and no longer, and keep it current. Clients and developers will both thank you.
Sources
- IEEE 830-1998 (superseded by ISO/IEC/IEEE 29148) — status of the classic SRS recommended practice
- W3C: Web Content Accessibility Guidelines (WCAG) 2.2 — accessibility conformance levels A, AA and AAA
- NIST SP 800-218: Secure Software Development Framework — defining security requirements for software development
Frequently asked questions
What should be included in a software requirements document?
A software requirements document should include the purpose, scope and out-of-scope items, a glossary, user types, numbered functional requirements, non-functional requirements such as performance, security and accessibility, integrations and data, constraints, assumptions, priorities, acceptance criteria and a change process. Smaller projects can combine sections, but don't skip non-functional requirements or scope.
What is the difference between an SRS and a BRD?
A business requirements document (BRD) explains the business need, goals and high-level outcomes, usually written for executives and stakeholders. A software requirements specification (SRS) translates those needs into detailed functional and non-functional requirements that developers and testers can build and verify. On smaller projects, the 2 are often combined into 1 document.
How long should a software requirements document be?
It should be as long as the project's risk and complexity require. A simple MVP might need 2 to 5 pages, while a regulated or fixed-price enterprise project might need dozens. Focus on clarity rather than length. Every requirement should be necessary, specific and testable, and anything that doesn't help someone build or verify the software can usually go.
Who writes the software requirements document?
It's usually led by a business analyst, product manager or project manager, with input from clients, end users, developers, designers and testers. On small projects, the founder or business owner may draft it with the development team. The key is that both business and technical people review it, since each side catches different gaps.
Are user stories the same as requirements?
User stories are one way to express functional requirements from the user's point of view, such as "As a client, I want to cancel online so I don't have to call." They work best paired with acceptance criteria. Stories alone often miss non-functional requirements, integrations and constraints, so most teams supplement them with a short requirements document.
Is there a standard template for an SRS?
Yes. Many SRS templates are based on IEEE 830-1998, which has been superseded by ISO/IEC/IEEE 29148, the current international standard for requirements engineering. You don't need to follow it exactly. The section outline in this guide covers the core content most projects need and can be adapted to your organization's own template.
How do you write testable requirements?
Make each requirement specific, measurable and limited to 1 idea. Replace vague words like "fast" or "easy" with measurable targets, such as load times or number of steps. Then add acceptance criteria, often in Given/When/Then format, that describe exactly what must happen. If a tester can't write a pass or fail test for it, rewrite it.
Was this guide useful
No reviews yet. Share your experience and help other readers.
Write a review
Manishdai
Manishdai writes about the technology that is reshaping every industry — from AI agents and cloud platforms to healthtech, fintech and the IT companies building it all across the United States.
manishdai.com