TL;DR
- A good requirements document has 7 sections: overview, users, functional requirements, non-functional requirements, integrations, data model, and acceptance criteria
- Write requirements as user stories: "As a [role], I want to [action], so that [outcome]"
- Every functional requirement needs a testable acceptance criterion
- Non-functional requirements must include specific numbers: "fast" is not a requirement
- The document should be detailed enough for a developer to build from without guessing
Why Requirements Documents Matter
In custom software projects, ambiguous requirements are the root cause of most cost overruns and delivery delays. When a developer has to interpret a vague requirement, they make the decision that seems most reasonable to them. That may not be what you wanted. By the time you see the result in a sprint demo, the decision has been built upon. Changing it then costs 3–5x more than it would have cost to clarify at the requirements stage.
A well-written requirements document isn't a bureaucratic exercise. It's the shared understanding between you and your development team about exactly what will be built. Time invested here pays back many times over in reduced rework.
The 7-Section Requirements Document Template
Section 1: Business Overview
Explains what the software needs to accomplish at a business level: not technical details. This section is the "why" that keeps the whole project aligned.
Template
Business Context: [What problem does this solve? What is the current state?]
Project Goal: [One sentence: what this software will do]
Success Metrics: [How will we measure whether the project succeeded in 6 months?]
Constraints: [Budget cap, go-live deadline, regulatory requirements]
Out of Scope: [Explicitly list what this project will NOT build]
Section 2: User Roles
List every type of person who will use the system. Each role will have different permissions, workflows, and priorities. Skipping this causes developers to design for one generic "user" and get permissions wrong.
Example
Administrator: Full system access; manages users, settings, integrations
Operations Manager: Views all data; creates/edits orders and shipments; runs reports
Warehouse Staff: Scans stock in/out; updates shipment status; cannot access finance data
Customer: Self-service portal; views own orders and invoices; cannot see internal data
Section 3: Functional Requirements (User Stories)
The core of the document. Write each requirement as a user story: As a [role], I want to [action], so that [outcome]. Group stories by module or feature area.
The "so that" clause is the most important part. It forces you to articulate why the feature matters: which often reveals simpler ways to achieve the same outcome.
Good examples
✓ As a warehouse manager, I want to scan a barcode to receive stock, so that inventory levels update in real-time without manual entry.
✓ As an operations director, I want to filter shipments by carrier, date range, and status, so that I can identify delayed deliveries and take action.
✓ As a customer, I want to download my invoice as a PDF, so that I can process payment through my accounts payable system.
Bad examples: too vague
✗ The system should have a dashboard
✗ Users can manage inventory
✗ The software should be easy to use
Section 4: Non-Functional Requirements
Non-functional requirements define the quality attributes of the system: how well it does what it does. These must have specific, measurable targets.
| Category | Vague (bad) | Specific (good) |
|---|---|---|
| Performance | System should be fast | All pages load in under 2s at 200 concurrent users |
| Availability | System should be reliable | 99.5% uptime SLA; planned maintenance windows only |
| Security | Data should be secure | AES-256 encryption at rest; TLS 1.3 in transit; OWASP Top 10 coverage |
| Scalability | Should handle growth | Handle 10x current transaction volume without re-architecture |
| Compliance | Should be GDPR compliant | Right to erasure within 30 days; audit log for all PII access; data retained <6 years |
Section 5: Integrations
List every external system the software must connect to. For each integration, specify:
- what data flows in/out
- direction (read/write/both)
- frequency (real-time, daily sync, on-demand)
- any known API documentation
Integration table template
System: Xero | Data: invoices, payments | Direction: write | Frequency: real-time | Auth: OAuth 2.0
System: Royal Mail API | Data: shipment creation, tracking | Direction: read/write | Frequency: on-demand
System: Legacy ERP (REST API) | Data: stock levels, product catalogue | Direction: read | Frequency: daily sync
Section 6: Data Model Overview
You don't need to design the full database schema: that's the architect's job. But you should describe the key entities (objects) in your business domain and how they relate to each other.
Example (logistics platform)
Customer → has many Orders
Order → has many Shipments → each Shipment has one Carrier and many Parcels
Parcel → has many ScanEvents (timestamp, location, status)
Order → linked to one Invoice in Xero (via external_invoice_id)
Section 7: Acceptance Criteria
Every user story needs acceptance criteria: specific, testable conditions that must be true for the feature to be considered complete. This is what your QA team (and you) test against.
Example acceptance criteria for a barcode scanning story
Given: A warehouse staff member scans a valid barcode
When: The scan is submitted
Then: The matching product's quantity increases by 1
And: A scan event is logged with timestamp, user ID, and quantity
And: The updated quantity is visible in the inventory dashboard within 5 seconds
Given: The barcode is not found in the product catalogue
When: The scan is submitted
Then: An error message is displayed: "Product not found: scan not recorded"
Common Requirements Mistakes to Avoid
| Mistake | Why It Hurts | Fix |
|---|---|---|
| Writing solutions not problems | Locks in approach before architecture is designed | Describe what user needs to accomplish, not how |
| No "out of scope" section | Ambiguous boundaries cause scope creep | Explicitly list what WON'T be built in v1 |
| Skipping non-functional requirements | Performance/security issues found at launch | Include concrete NFRs for every project |
| Undefined edge cases | Developers handle edge cases differently; bugs at launch | Include "given/when/then" for failure paths too |
| One-person document review | Process knowledge held by one person causes gaps | Have end users review requirements for their workflows |