User stories explained: how to describe features so they get built right

A clinic owner writes in the requirements for her new booking system: “Customers must be able to book online.” The developer builds a calendar where the customer picks a time. At the first demo it turns out customers need to choose a practitioner, some treatments require a consultation first, a deposit must be paid, and the customer should get a text message the day before. None of it was wrong. The sentence was simply so short that everyone filled the gaps with their own assumptions. User stories with acceptance criteria are the tool that closes those gaps before code is written.

This guide is written for those of you buying software who want to describe your needs so precisely that the supplier builds what you mean. It applies to apps, web apps, portals and websites with features alike.

What is a user story?

A user story describes one thing a specific user wants to be able to do, and why. The format has three parts: the role, the action and the benefit. The role makes you think about who the feature is for. The action describes what they want to do. The benefit, the “so that” part, is the most important, because it tells the designer and developer which problem the feature solves, so they can suggest a better solution if one exists.

Template: As a [role] I want [action] so that [benefit]. Example: As a customer I want a text message the day before my appointment so that I don’t forget it.

User stories come from agile software development and are often described with the three Cs: Card, Conversation and Confirmation. The card is the sentence itself. The conversation is the dialogue between you and the team where details are clarified. The confirmation is the acceptance criteria, which decide when the story is done. A story is in other words an invitation to a conversation, and it is the conversation that creates shared understanding.

How do you write a good user story?

The most widely used checklist is called INVEST. If a story meets the six points, it is typically ready to be estimated and built. Use the list when reviewing your drafts:

• Independent: the story can be built and delivered on its own.
• Negotiable: it describes the need and leaves the solution open for dialogue.
• Valuable: it delivers value to a user or the business.
• Estimable: the team understands it well enough to judge its size.
• Small: it can be built and tested within a few days.
• Testable: there are clear criteria for when it works.

User story examples from a booking system

Here are 12 user stories from a typical booking system for a clinic or service business. Note that there are three roles: the customer, the staff member and the administrator. Many forget the last two, even though they use the system every day.

What are acceptance criteria, and how do you write them?

Acceptance criteria are the concrete conditions that must be met before a story is done. They are your most important protection as a client, because they turn “done” into something you can test. A popular format is Given–When–Then: given a certain situation, when the user does something, then this happens. Here are the criteria for the cancellation story:

• Given the appointment is more than 24 hours away, when the customer taps “Cancel” in the confirmation email, then the slot is released and the customer gets a receipt.
• Given the appointment is less than 24 hours away, when the customer tries to cancel, then the clinic’s phone number and an explanation of the rule are shown.
• Given the customer paid a deposit, when the appointment is cancelled in time, then the deposit is refunded automatically.
• Given the appointment is cancelled, then another customer can book the slot immediately.
• Given an appointment is cancelled, then the practitioner is notified in their overview.

Notice how many questions five short criteria answer: what the 24-hour rule means in practice, what happens to the payment, and who gets notified. Each of them would otherwise have surfaced as a discussion at the demo or as a bug after launch. The criteria are also what you test against when you approve the delivery, and they are a good starting point for a usability test.

What is the difference between epics, user stories and tasks?

How do you prioritise user stories with MoSCoW?

MoSCoW is the most widely used method for prioritising a list of user stories. Each story goes into one of four categories. The hard part is being honest about what is a must. A useful question is: “Can we launch without it, and will anyone still use the solution?” If the answer is yes, it is a should or a could. The method comes from the DSDM framework, which recommends that must-have stories make up no more than about 60 % of the effort, leaving room for the unexpected.

How do user stories turn into a fixed price?

A prioritised list of user stories is the best basis for a fixed price, because both you and the supplier can see exactly what is included. Our packages are built around the number of features: Small has 12 features and 1 integration for DKK 18,000 for web or DKK 28,000 for an app, Medium has 24 features and Large 36. A must-have story often equals one feature, so a good list makes it easy to see which package fits. See the details under pricing, and read more about the difference between fixed price and hourly billing.

Which mistakes do we see most often in user stories?

• The role is “user”. Write which user: customer, staff member, administrator, accountant.
• The benefit is missing. Without “so that” the team cannot suggest a better solution.
• The story describes a screen in place of a need, for example “a page with a dropdown”.
• The story is too big. “As a customer I want to manage my bookings” is an epic.
• No acceptance criteria, so “done” becomes a matter of taste.
• Everything is a must. Then nothing is prioritised, and the budget decides instead of the value.
• Error cases are forgotten: what happens when the payment fails or the slot is taken?

Template: how to get started with your user stories

1. List every user type who will use the solution, including your own staff.
2. For each user type, write the 3–5 most important things they need to do.
3. Phrase each one as “As a [role] I want [action] so that [benefit]”.
4. Split large stories until each can be built in a few days.
5. Add 3–6 acceptance criteria to every must-have story.
6. Prioritise with MoSCoW, and be strict about the must category.
7. Write the non-functional requirements as a short list: security, speed, accessibility, hosting.
8. Review the list with your supplier before asking for a fixed price.

User stories are best written together, and a product discovery workshop is the obvious place to do it. If you prefer a more traditional document, the stories can go straight into our requirements specification template. And to understand how stories are used during development, read our guide to agile vs waterfall. If you already have a list, send it to us and get a written fixed-price proposal within 24 hours.