How to Write an App Requirements Document
A useful app requirements document explains why the app exists, who uses it, what each user must be able to do, and how you will know each requirement is done. Include goals and success metrics, user roles, user stories with acceptance criteria, key screens or flows, integrations and data, non-functional needs such as security, accessibility and performance, and an explicit out-of-scope list. Keep it short enough to read in one sitting, and update it as decisions change.
- Start with business goals and measurable success criteria, not a feature list.
- Write requirements as user stories with testable acceptance criteria.
- Non-functional requirements (security, accessibility, performance, compliance) change estimates as much as features do.
- An explicit out-of-scope list prevents more disputes than any other section.
- Prioritize every requirement so the team knows what to cut if time or money runs short.
The Steps
- State the goal and success metricsOpen with the problem, the business outcome and two or three measurable targets, such as cutting phone bookings by half or reaching 500 weekly active users within six months.
- Define user rolesList each type of user, such as customer, staff member and administrator, with a sentence on what they need and how often they use the app. Each role usually needs different screens.
- Write user storiesFor each role, write stories in the form: as a role, I want an action, so that a benefit. Group them by journey, such as sign-up, booking, payment and support.
- Add acceptance criteriaUnder every story, list the specific conditions that make it done, including error cases. Criteria should be testable by someone who did not write them.
- Document integrations and dataName every external system, what data flows in which direction, how often, and who owns the account. Note existing data that must be migrated and its rough volume.
- Specify non-functional requirementsSet targets for security, privacy, accessibility, performance, supported devices and operating system versions, uptime, and any regulations such as HIPAA that apply to your data.
- List what is out of scopeWrite down features, platforms and integrations that are deliberately excluded from this release. This protects both your budget and the team from assumptions.
- Prioritize and reviewLabel each story must, should or could, then walk the document through with the development team. Their questions reveal gaps; update the document and version it.
Why the Document Matters More Than the Template
Estimates are only as good as the information behind them. When two firms quote the same idea and their prices differ by a factor of three, the cause is usually that each one imagined a different app. A requirements document makes the hidden assumptions visible: how users log in, what happens when a payment fails, whether staff need an admin area, which systems the app must talk to. It also becomes the reference point for testing and acceptance, so everyone agrees on what "done" means.
You do not need a 60-page specification. For most small and mid-sized business apps, 8 to 20 pages, plus wireframes or flow sketches, is enough to estimate and build a first release.
A Practical Structure
- Overview: the problem, the business goal, success metrics and the target launch window.
- Users and roles: who uses the app and what each role is allowed to do.
- User journeys: the main flows from start to finish, with sketches or wireframes if you have them.
- User stories and acceptance criteria: the detailed functional requirements, grouped by journey and prioritized.
- Integrations and data: external systems, data ownership, migration and reporting needs.
- Non-functional requirements: security, privacy, accessibility, performance, devices, uptime and compliance.
- Out of scope and open questions: exclusions for this release and decisions still pending.
Writing Stories and Criteria That Work
The UK government's service manual offers a clear model for writing user stories: who the user is, what they need, and why, followed by acceptance criteria. Here is an example for a clinic booking app:
Story: As a returning patient, I want to rebook my last appointment type in two taps, so that I do not have to search again.
Acceptance criteria:
- The home screen shows the patient's last appointment type and provider when one exists.
- Tapping it shows the next available slots for that provider, with an option to choose another provider.
- If the provider has no openings in the next 30 days, the app says so and offers the waitlist.
- A confirmation appears on screen and by email within one minute of booking.
Notice what makes these useful: they cover the normal path and the edge cases, use concrete numbers, and can be tested by someone who did not write them. Avoid words like "fast," "easy" or "intuitive" without a measurable definition.
Non-Functional Requirements People Forget
These rarely appear in a founder's first draft, yet they change cost and timeline substantially:
- Security: login method, multi-factor authentication, session length, and data encryption. Referencing the OWASP MASVS control groups gives developers a concrete target. See how to secure a mobile app.
- Accessibility: state the target, typically WCAG 2.2 Level AA, and require testing with screen readers. See how to make your app accessible.
- Supported devices and OS versions: the oldest iOS and Android versions you will support, tablets or not, and offline behavior.
- Performance: for example, key screens load within two seconds on a typical connection.
- Compliance and data residency: HIPAA, PCI DSS scope for payments, children's privacy rules, and where data is stored.
- Analytics and admin: what you need to measure and what staff need to manage without calling a developer.
Common Mistakes
- Describing solutions instead of needs. "Add a dropdown with all 40 services" locks in a design; "a customer can find the right service in under 30 seconds" lets designers solve it well.
- Copying a competitor's feature list. Their app reflects years of iteration and a different business. Start from your own users' journeys.
- Treating every item as must-have. If everything is a priority, nothing is. A first release with a third of the stories marked "should" or "could" gives the team room to deliver on time.
- Leaving out the admin side. Someone has to manage users, refunds, content and reports. Those screens are real work and belong in the estimate.
- Skipping the unhappy paths. Failed payments, expired sessions, lost connectivity and duplicate sign-ups are where apps feel broken.
Keeping the Document Useful
A requirements document is a living reference, not a contract to freeze. Version it, record decisions with dates, and move resolved open questions into the body. When a new idea comes up mid-build, add it as a story with a priority instead of slipping it in verbally; that keeps the budget honest. Our guide to budgeting for app development explains how prioritized stories make scope cuts painless, and a solid document is the best input to choosing a development company.
Sources and Further Reading
We link to the primary documentation so you can verify the details yourself.
- Writing user stories, GOV.UK Service Manual
- Mobile Application Security Verification Standard (MASVS), OWASP
- Web Content Accessibility Guidelines (WCAG) 2.2, W3C
- Human Interface Guidelines: Accessibility, Apple Developer
Related Questions
Should I write the requirements or let the developer do it?
Write the business side yourself: goals, users, journeys and priorities, because only you know them. Then let the development team refine the technical detail and acceptance criteria during discovery. The best documents are co-written, with the business owning the why and the team owning the how.
Do I need wireframes in the requirements document?
They help a lot. Even rough sketches of key screens remove ambiguity that text alone leaves. Designers can turn them into proper wireframes during discovery. If you cannot sketch, list what information and actions each screen needs, and the team can draw from that.
How detailed should acceptance criteria be?
Detailed enough that a tester could check each one without asking you what you meant. Cover the main path, the most likely errors and any limits, such as maximum file size or time windows. If a criterion cannot be verified with a yes or no, rewrite it.
Is a requirements document the same as a statement of work?
No. The requirements document describes what the product must do. A statement of work is a contract document covering deliverables, timeline, payment and responsibilities, and it usually references the requirements. Keep them separate so product changes do not require rewriting the contract each time.