User Story Example
Six finished user stories with acceptance criteria for one feature, showing how to write requirements a developer can estimate and you can test.
1 Overview
A user story describes one thing a user wants to do, in one sentence: as a role, I want a goal, so that I get a benefit. It is the smallest unit of a requirement that still makes sense to a non-developer. A set of stories for one feature tells the team what to build and tells you what to check before you accept it.
The sentence alone is not enough. What makes a story usable is its acceptance criteria: a short list of conditions that are either met or not. They turn a wish into something that can be estimated, built and tested.
What a good story contains
- A specific role. Not "the user" but the patient, the receptionist, the administrator. Different roles need different things from the same screen.
- One goal. If the sentence contains "and", it is probably two stories.
- The benefit. It tells the developer why, which helps when a detail is not covered. If you cannot name a benefit, question whether the story is needed.
- Three to seven acceptance criteria, each checkable with yes or no, including what happens when something goes wrong.
- A priority, so that the team knows what can be left out if time runs short.
- Anything agreed as out of scope, noted with the story set.
Writing acceptance criteria
Write what can be observed, not how it is built. "The patient sees only slots with the same therapist" can be tested by anyone. "The system uses a calendar component" is a design decision and does not belong here.
Put numbers where words are vague. "Fast", "soon" and "easy" cannot be tested; "up to 24 hours before the appointment" can.
Cover the unhappy paths: the slot was taken a second ago, the deadline has passed, the email cannot be delivered. Most disputes at acceptance are about cases nobody wrote down.
Common mistakes
Stories without a role or benefit, which are really task lists: "add a button to the dashboard".
Stories that are too large. "As a patient I want to manage my appointments" hides booking, moving, cancelling and reminders. If it cannot be built and shown within a few days, split it.
Technical tasks written as stories. "As a developer I want a database table" has no user and no benefit. Such work is real, but it belongs in the team's task list.
Criteria that describe the layout in detail. Leave that to the design; describe behaviour.
Forgetting the people behind the counter. Almost every feature for customers creates work or needs information for staff. Write those stories too.
Treating stories as a contract that replaces conversation. A story is a reminder to talk a detail through, and the result of that talk goes into the criteria.
How to use the example
Read the six stories as one set: they cover the customer, the staff and the edge cases of a single feature. For your own feature, list the roles first, write one story per goal, then add criteria until you could test the story yourself without asking anyone.
2 Example
These stories describe one feature of a patient portal for an invented physiotherapy practice: moving an appointment online. The practice, the people and all figures are made up for illustration.
Feature: Reschedule an appointment online
Fenmoor Physiotherapy, patient portal. Written by Priya Halloran (practice manager) with Owen Ridley (developer). Version 3.
Background: about 40 calls a week at the front desk are requests to move an appointment. Patients should be able to do this themselves. Agreed rule: moving is free up to 24 hours before the appointment.
Story 1: See my upcoming appointments (must)
As a patient, I want to see my upcoming appointments after logging in, so that I know which one I need to move.
Acceptance criteria:
- The list shows date, time, therapist and branch for every future appointment.
- Appointments are sorted by date, the next one first.
- Past appointments are not shown in this list.
- If there are no future appointments, the page says so and offers a link to book one.
Story 2: Move an appointment to a free slot (must)
As a patient, I want to move an appointment to another free slot, so that I do not have to call the practice.
Acceptance criteria:
- Each appointment that starts in more than 24 hours has a "Reschedule" action.
- The patient sees only free slots with the same therapist, at the same branch, within the next 28 days.
- After confirming, the old slot is free again and the new one is booked.
- If the chosen slot was taken in the meantime, the patient sees a message and the updated list of slots; the original appointment stays unchanged.
- An appointment can be moved at most twice; after that the action is replaced by the practice phone number.
Story 3: Understand why I cannot reschedule (must)
As a patient, I want to be told when it is too late to move an appointment, so that I know what to do instead.
Acceptance criteria:
- For appointments that start in 24 hours or less, the action is not available.
- In its place the page shows the reason and the phone number of the branch.
Story 4: Receive a confirmation (must)
As a patient, I want an email after rescheduling, so that I have the new time in writing.
Acceptance criteria:
- The email is sent within five minutes and names the old and the new date and time, the therapist and the branch address.
- The email contains a calendar file for the new appointment.
Story 5: See changes at the front desk (must)
As a receptionist, I want to see which appointments patients have moved themselves, so that I am not surprised by changes in the day plan.
Acceptance criteria:
- Moved appointments are marked in the practice calendar for seven days.
- The marker shows when the change was made and from which original time.
- A daily list at 7:00 shows all changes for that day made since the previous morning.
Story 6: Block a patient from online rescheduling (should)
As a practice manager, I want to switch off online rescheduling for individual patients, so that I can handle repeated late changes personally.
Acceptance criteria:
- The setting is available in the patient record and can be changed only by the role practice manager.
- A blocked patient sees the phone number in place of the action, without a reason.
Not part of this feature
Cancelling without a new slot, changing the therapist, reminders by SMS.
3 Who this is for
Product manager
You get a complete story set for one feature, with priorities and edge cases, as a pattern for splitting your own features into pieces that can be estimated, built and accepted one at a time.
Founder
You see how to describe what you want in plain sentences that a development team can price, and how acceptance criteria protect you from the discussion about whether something was part of the order.
Project manager
You can use the criteria as a ready checklist for acceptance, and the split into must and should stories shows how to keep a release date when time runs short.
4 Questions and answers
How many acceptance criteria should a user story have?
Usually three to seven. With fewer than three, the unhappy paths are probably missing. With more than seven or eight, the story is likely too large and should be split, often along the line between the normal case and the special cases.
Who writes the user stories, the client or the developers?
The person who knows the users best writes the sentence and the benefit; that is usually the client or the product owner. The acceptance criteria are best finished together with the developers, because they ask about the edge cases a non-developer does not think of.
Do user stories replace a requirements specification?
For a single feature or an agile project they often do. For a fixed-price contract you normally still need a document that fixes the overall scope, the non-functional requirements such as performance and security, and what is excluded. Stories can form the functional part of it.
Planning a project like this?
Tell us what you are building. You get a straight answer on scope, approach and effort.