How to Write a Software Requirements Brief, with a Worked Example
TL;DR
A useful brief explains what happens when the happy path fails. Follow a booking request from vague idea to testable scope and supplier questions.
Updated . Added a worked booking brief, state and exception tables, testable acceptance criteria and a downloadable requirements template.
“Customers should be able to book online” sounds like a requirement. It is closer to a heading. It does not say whether a booking reserves a scarce slot, whether payment is required or what happens when two people choose the same appointment.
Requirements gathering turns that heading into decisions a team can build and test. The aim is not to predict every feature for the next three years. It is to define the current problem, the important journeys, the constraints and the evidence that will show whether the proposed software works.
A useful brief lets two suppliers estimate substantially the same job. It also gives the client a way to recognise missing scope before it becomes an argument during delivery. The fictional booking example below shows the level of detail that changes a proposal.
Start with the problem and the people involved
Write down who struggles with the current process and what they are trying to achieve. Include the people who correct mistakes, manage exceptions and support customers. Their work often reveals requirements missing from a feature list.
For the example, a service business receives appointment requests by email. A coordinator checks availability, contacts the customer and confirms the booking. The problem is repeated coordination and uncertainty about whether a requested time is actually reserved.
Do not jump straight to “build a calendar”. First investigate the current journey, the scheduling rules and the reason people contact the coordinator. The GOV.UK discovery guidance makes a useful distinction between understanding a problem and committing to a solution. A commercial brief benefits from the same discipline without needing to copy a government project process.
Distinguish business, functional and quality requirements
A business requirement explains the outcome sought. A functional requirement describes behaviour. A quality requirement specifies how well the behaviour must work under stated conditions. Keep constraints and assumptions visible alongside them.
| Type | Weak wording | More useful wording for the fictional example |
|---|---|---|
| Business outcome | Improve bookings | Reduce avoidable coordinator exchanges while preserving accurate reservations |
| Functional | Add a booking form | Let a customer request an available slot and receive a clear confirmation state |
| Quality | Make it fast | Agree a response-time target under a defined concurrent workload |
| Constraint | Integrate our systems | Use the existing scheduling system as the availability source |
| Assumption | Customers have email | Confirm whether an alternative confirmation channel is needed |
Do not invent a response-time threshold just to make the brief look precise. Identify the user need and the test conditions, then agree a target with the team. A number without a workload, device or measurement method may be no more useful than “fast”.

Turn a booking request into a testable requirement
Begin with a user need: a customer wants to reserve a suitable appointment and know whether it is confirmed. Then define the states. In this fictional scope, a selected slot is held temporarily while the customer supplies details. It becomes confirmed only when the scheduling system accepts the booking.
The hold duration is a business decision to agree, not a default this article prescribes. Record what happens if it expires. Do not leave the interface showing “confirmed” while the backend is still processing an uncertain request.
| Situation | Required behaviour | Evidence for acceptance |
|---|---|---|
| One customer confirms an available slot | Create one booking and show confirmation | Booking reference matches the scheduling record |
| Two customers confirm the last slot | Only one receives that slot | Other customer receives an accurate unavailable state |
| The response times out | Check the transaction outcome before retrying | No duplicate booking; user sees a recoverable state |
| Customer returns after hold expiry | Recheck availability | No promise based on an expired hold |
| Coordinator cancels the appointment | Update the authoritative record and notify through the agreed channel | History shows who changed what |
These are proposed acceptance cases, not results from a completed application. They expose questions the team must resolve before quoting confidently.
Make acceptance criteria describe outcomes
The GOV.UK user-story guidance treats acceptance criteria as outcomes used to establish whether a user need has been met. Apply that idea to the booking journey: the customer knows the actual state, the record exists once and staff can identify it.
Avoid specifying a particular button or library unless it is a genuine constraint. “Use a green confirmation button” does not prove that the slot is reserved. A design detail and a behavioural requirement belong in different parts of the brief, even when they are related.
Include negative cases. What must the system refuse? Who must not see a booking? Which changes require staff authority? Define the outcome clearly enough that a tester can challenge it with a realistic example rather than only follow a happy-path script.
Describe the data and the integration contract
List the information each step needs, its source and who may change it. For the booking example: service type, appointment time, customer contact, booking state and reference. Separate necessary information from fields someone might find useful later.
Identify the authoritative system for availability. State how recent the displayed availability must be and when it is checked again. Ask what the external API returns for an unavailable slot, expired credentials, rate limits and uncertain transaction outcomes.
Amazon’s idempotent API discussion explains a relevant engineering issue: retries must be designed so that an operation’s effect is not accidentally repeated. The client brief need not dictate the implementation, but it should require the visible result—no duplicate reservation after an uncertain response.
If API access has not been confirmed, label it as a dependency. Do not let every supplier assume a different integration route and then compare their prices as though the scope were identical.
Use interviews, observation and workshops for different questions
Interview the sponsor about the business problem and decision constraints. Observe coordinators doing the current work to find exceptions and manual checks. Use a workshop to resolve conflicting rules with the people authorised to make those decisions.
Bring concrete artefacts: an anonymised request, a cancellation, a rescheduling case and an example that required several exchanges. Walk through them. Asking “what features do you want?” often produces a larger wishlist than asking “what happened here, and why?”
Record disagreements instead of smoothing them into vague wording. If sales promises flexible rescheduling while operations needs a cutoff, the software cannot resolve that policy conflict by itself. Give the decision an owner and explain which part of the estimate remains uncertain until it is resolved.
Define a first release and explicit exclusions
A small first release should still complete a useful journey. A booking form that creates requests but leaves staff without a way to resolve failures may simply relocate the work.
For the fictional example, the first release could include requesting, confirming and staff cancellation for one service type. Recurring bookings, group appointments, waiting lists and online payments might be excluded. Those are scope choices, not recommendations for every business.
State how excluded needs are handled temporarily. If payment remains outside the app, explain the existing process. If a customer needs to reschedule through staff, make that route clear. An exclusion without an operational alternative can leave a gap in the service.
The app development timeline guide explains why dependencies influence delivery dates. A brief that identifies those dependencies makes timeline discussions more credible.
Give suppliers an assumptions and questions section
Ask every supplier to return the same categories: understood scope, exclusions, assumptions, client dependencies and unresolved questions. Require a distinction between confirmed integration work and discovery needed to establish feasibility.
Use the booking conflict case to compare proposals. Does the quote include concurrency handling and recovery, or only a screen that submits a form? Does someone own accessible error messaging? Is staff support included? These differences can explain a price gap more clearly than a headline day rate.
Keep the brief versioned. When a requirement changes, record the reason and the affected acceptance cases. Change control should support informed decisions, not pretend that learning stops when a document is signed.
Leave with a brief that can be challenged
Download the requirements brief and worked booking cases. It includes prompts for users, states, exceptions, data, quality targets and decisions still outstanding. Fill the evidence fields before treating the document as an agreed build scope.
For choosing a delivery partner, use the separate app agency selection guide. This brief defines the job; the selection process evaluates who can deliver it.
Pixelfield’s app development team can help turn an uncertain product idea into a testable scope. Bring one real journey and an example of where it currently fails. That is a stronger start than a long list of features with no acceptance conditions.
3 Comments