← Back

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.

Conceptual illustration for How to Write a Software Requirements Brief, with a Worked Example

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”.

Diagram showing User: Coordinator, State: Held slot, Exception: Conflict, Evidence: Passing test.
Editorial decision aid; worked examples are fictional, not measured client results.

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.

Michal Vávra
Written by
Head of AI & Development

Michal has been with Pixelfield since September 2012 and has held technical leadership roles since 2017. He is the technical force behind our most demanding builds, combining AI expertise with the infrastructure and software architecture needed to make it work in production. His work spans LLM applications, multi-agent orchestration and complex integrations. He sets the engineering standards behind reliability, performance and scale, and guides the team through the decisions that determine how a system runs long after launch.

3 Comments

Leave a reply

Your email address will not be published. Required fields are marked *.