Key takeaways
- A requirements document is useful only if developers, designers and testers keep using it, so keep it short, specific and current.
- Start with the problem, a measurable goal, user roles and one named decision-maker before listing any features.
- Write each functional requirement so a developer can build it and a tester can check it, using acceptance criteria and unique IDs.
- Give non-functional requirements such as performance, security and accessibility measurable targets, because this is where quotes and delivered products most often diverge.
- Define what is out of scope, prioritise with a method like MoSCoW, and describe release one as the smallest version that meets the goal.
- Review the document with your developer before work starts and log every change with its cost and timeline impact.
Most software projects that go wrong do not fail because developers cannot code. They fail because the people paying for the software and the people building it carried different pictures in their heads, and nothing written down exposed the gap until it was expensive to fix. A software requirements document is meant to close that gap. Too often it does the opposite: a 60-page file written once, signed off, and never opened again.
The reasons developers ignore these documents are consistent. They are too long, vague about what "done" means, silent on performance and security, unprioritised, or disconnected from the business goal that justified the project. A document that is skimmed once and abandoned adds cost without reducing risk.
This guide shows how to write a requirements document that works as a daily reference. It covers how to frame the problem, write requirements that can be built and tested, handle non-functional needs, set scope and priorities, support the text with flows and examples, keep the document current and review it with your developer before work starts.
It is written for founders, business owners, product managers and technology leaders who are commissioning a website, mobile app or custom software, with or without a technical background. If you are comparing quotes, choosing a contract model or preparing for a discovery phase, a clear document will improve every one of those conversations.
What a requirements document is, and why developers ignore most of them
A software requirements document is a shared written agreement on what the software must do, for whom, and under what constraints. It serves four readers: the developer who builds it, the designer who shapes it, the tester who checks it and the business owner who pays for it. It sits after discovery and before design and build. The software discovery phase produces the raw material, and the document turns it into something a team can work from. Weak requirements are only one of the common reasons software projects fail.
Why most requirements documents fail
Most are too long to read, written once and never updated, or worded so loosely that two people read them differently. Many are feature wish-lists with no priorities and no link to a business goal. Research on ISO/IEC 29148, the standard for requirements engineering, notes that poorly written user needs send inaccurate messages to the development team, and that incomplete or ambiguous descriptions do not guide good software.
Requirements document, PRD and technical spec: how they differ
It is not a contract, a design brief or a technical specification. A PRD covers purpose, users and priorities. An SRS lists detailed behaviour and constraints. Small teams often combine the two.
Start with the problem, the goal and the people
Open the document with a one-page context. A developer who reads only this page should know what business problem the software solves, how success will be measured, who will use it and what limits the team must work within.
Write the goal as an outcome you can measure
State the goal as a result, not a feature. "Reduce order-processing time" or "remove duplicate data entry" gives the team something to test against. "Build a dashboard" does not. As an illustrative, hypothetical example, the goal for an internal approvals tool might be: cut the average approval time from five days to two. Every requirement can then be checked against that sentence.
Name the users and the decision-maker
List each user role and what that role needs to do, for example requester, approver and administrator. Then list stakeholders and name one person who resolves disagreements. Without that person, conflicting feedback stalls the project.
Close the page with the following:
- Assumptions and dependencies: what you expect to be true and what you rely on others to deliver.
- Constraints: budget range, deadline, regulation and existing systems.
- Glossary: short definitions, because teams often use one word, such as "customer" or "order", to mean different things.
Write functional requirements a developer can build and a tester can check
A functional requirement states something the system must do. Write each as a user story, as a [role], I want [action], so that [benefit], then add acceptance criteria in Given/When/Then form: Given a starting condition, When an action happens, Then a specific result follows.
From vague to testable: a worked example
Illustrative example. Vague: "Users can reset their password easily." Testable rewrite, FR-012: As a registered user, I want to reset my password by email, so that I can regain access without contacting support.
- Given a registered email, when the user submits it, then the system must send a reset link valid for 60 minutes.
- Given an expired link, when the user opens it, then the system must show an expiry message and offer a new link.
- Given an empty email field, when the user submits, then the system must show an error and send nothing.
- Given an account with no reset permission, when a reset is requested, then the system must refuse and log the attempt.
Words that signal a weak requirement
Good requirements are commonly described as necessary, unambiguous, complete, consistent, feasible and verifiable, in the spirit of ISO/IEC 29148 guidance. Research on "requirements smells" uses that guidance to treat concrete wording symptoms as signs of a quality problem. Watch for "fast", "easy", "user-friendly", "etc." and "as appropriate".
Keep one requirement per statement. Use "must" for mandatory and "should" for optional, consistently. Give every requirement a unique ID so it traces to a task and a test.
Cover non-functional requirements: the section most documents skip
Functional requirements say what the system does. Non-functional requirements say how well it must do it. This is where a quote and a delivered product tend to diverge. If nobody wrote "must support 500 concurrent users" (a hypothetical figure, used here only as an illustration), nobody built or tested for it.
Turn quality words into measurable targets
Words such as "fast" or "secure" cannot be tested. Give each target a number and say how it will be measured, for example page response time under a stated load, checked with a load test. If you do not know the number, write the question down and agree it with your developer. Never leave the line blank.
Security, accessibility and performance: what to specify
- Performance: response time targets under expected load, set with your developer.
- Security: user roles, authentication method, data protection and audit logs.
- Availability and backup: acceptable downtime, backup frequency and recovery expectations.
- Scalability: expected users now and in 12 to 24 months.
- Accessibility: name WCAG 2.2, the W3C accessibility guideline, as the standard.
- Browsers and devices: list the versions and screen sizes that must work.
- Compliance: applicable regulations and where data must be stored.
- Maintainability: code documentation and handover expectations.
Hosting and deployment expectations belong here too. Zero One Creation works across cloud infrastructure and DevOps, so these questions are best settled before development begins.
Define scope, priorities and integrations
Scope is where most disputes begin. Write what is included in plain terms, such as "customer login, order history and invoice download", so everyone reads the same boundary.
Say what is out of scope
An out-of-scope list matters as much as the in-scope one, because assumptions rarely get written down. If you do not expect a native mobile app, multi-language support or an admin reporting dashboard in this phase, say so. Add a "future, not now" parking lot so good ideas are recorded without inflating the budget.
Prioritise with Must, Should, Could, Won't
The MoSCoW method sorts every requirement into four groups: must have, should have, could have and won't have this time. A simpler alternative is a release-one and release-two split. Either way, define release one as the smallest version that delivers the goal from your context page, not the smallest version that looks impressive.
Integrations and data migration
List every external system the software touches, for example a payment gateway, CRM, ERP, email service or identity provider. For each one, record:
- What data moves, and in which direction
- Who owns the system and who can approve changes
- Where the API documentation is
- Who will supply access credentials, and by when
Missing documentation and credentials are common causes of delay, so treat them as dependencies. Our guide on how API-first development future-proofs business systems explains why clean interfaces pay off later.
Finally, describe the data you already have: where it lives, its quality, what must be migrated and how long records must be kept.
Add screens, flows and examples so words are not the only evidence
Text alone leaves gaps. Two people can read the same requirement and picture different screens. Pair the written requirements with visuals that show what you mean.
Draw a flow diagram for each critical journey, such as sign-up, checkout or approval. Annotate each step with the IDs of the requirements it relies on. Any step with no ID points to a gap, and any requirement that appears nowhere may be unnecessary.
Use prototypes to find missing requirements early
Review the design and the requirements together. A wireframe or clickable prototype often exposes what the text missed: an empty state, an error message, a screen for a role nobody described. Zero One Creation's UI/UX Design work includes user research, prototyping and design systems, which supports this kind of joint review.
Add real examples wherever output matters:
- Sample data, including awkward cases such as long names or missing values.
- Sample reports, ideally a real exported file. It removes more doubt than a paragraph describing it.
- Sample emails and notifications, with the exact wording and triggers.
If you include reference screenshots from other tools, label them similar to, not identical to. That way they show intent without being read as a specification to copy.
Structure the document and keep it alive
A practical outline
As a guideline, not a sourced figure, most projects fit in 10 to 20 pages. Use this order:
- Purpose and goals
- Users and roles
- Scope and out of scope
- Functional requirements, grouped by feature area
- Non-functional requirements
- Integrations and data
- Constraints and assumptions
- Open questions
- Glossary
- Change log
Use clear headings and numbered IDs, and keep the document in a shared tool your developer already opens, such as a wiki or issue tracker. Emailed Word versions go stale within a week. Keep open questions as a short list, each with an owner and a date.
Version control and change requests
Record every change with a date, an author, the reason and the impact on cost and timeline. This keeps changes visible and stops scope drifting. It also ties to your contract. A fixed price is only as reliable as the requirements behind it, as explained in fixed price vs time and materials. On time and materials, the document works as a living backlog.
How much detail suits an agile project
Agile teams can use a lighter format: a product vision, a prioritised backlog and acceptance criteria for each item. Lighter does not mean none. Without written goals and testable criteria, the team still builds from assumptions, and disagreements surface late.
Review it with your developer before work starts
Before development begins, hold a walkthrough. Ask the developer to read the document beforehand, then go through it together and flag anything ambiguous, risky or missing. Treat every question as a sign the process is working. A question now costs minutes; the same gap found mid-build costs rework.
Ask the team to estimate from the document, then compare the estimates. A wide gap usually points to a requirement that people read differently.
A pre-build review checklist
- Every requirement is testable.
- Every requirement traces to a goal.
- Nothing is left blank.
- Out of scope is written down.
- Non-functional targets are numbers.
- Open questions have owners.
- The decision-maker has signed off.
Mistakes that make documents useless
- Writing the solution instead of the problem. Dictating technology without a reason removes options that may serve you better.
- Copying a template without adapting it. Empty or irrelevant sections hide the parts that matter.
- One person writing alone. Missing perspectives surface later as change requests.
- Treating sign-off as the end. The document needs to keep changing with the project.
If your team has no time to write it, a software discovery phase can produce it jointly. Zero One Creation offers technology consulting and custom software development for this purpose; see zeroonecreation.com. To vet a supplier first, read choosing an app development partner and the red flags.
Frequently Asked Questions
At minimum: the problem and goal, user roles, functional requirements with acceptance criteria, non-functional requirements with measurable targets, in-scope and out-of-scope lists, priorities, integrations, data needs, and a list of open questions. Screens, flows and sample data should support the written text. A change log keeps it accurate over time.
For most business projects, roughly 10 to 20 pages is enough. Length matters less than usefulness: every section should help someone build, test or decide something. Small projects can be shorter, and complex systems may need supporting appendices rather than a longer main document.
Functional requirements describe what the system does, such as letting a user reset a password or export a report. Non-functional requirements describe how well it does it: speed, security, availability, accessibility, device support and compliance. Both need to be testable, and non-functional targets should be stated as numbers where possible.
Yes, but it can be lighter. Agile teams still need a clear vision, a prioritised backlog, acceptance criteria for each story and agreed non-functional targets. What changes is that the document evolves in small steps rather than being fixed up front.
Ideally both. The client knows the business problem, users and constraints, while the developer knows what is feasible, what is ambiguous and what affects cost. A client-led draft reviewed and refined with the development team usually produces the most accurate result.
A product requirements document (PRD) focuses on what the product should achieve and for whom, usually from a business and user perspective. A software requirements specification (SRS) goes into more detail about system behaviour and technical constraints. Small teams often combine them into one document.
Treat sign-off as a baseline, not a freeze. Log each change with its date, author, reason, and the effect on cost and timeline, and have the named decision-maker approve it. This keeps the document accurate and prevents disputes later, whichever contract model you use.



