011 min
What goes wrong without user stories
Picture a team that builds a grocery delivery app. A support agent reports that customers keep phoning to move their delivery to another time. The product manager passes the request to the engineers as one line in a long requirements document.
The system shall support modification of the delivery time slot.
An engineer reads the line and adds an editable time field to the internal admin screen. The line is correct, and the result is useless, because customers never see the admin screen. The line says what the system does. It does not say who needs the change or why, and nobody can ask the author what it meant.
So the engineer guessed, and the team found out at release. Long specifications fail this way in every field: the sentence no longer names the person, and the reader guesses what is missing. Teams needed a requirement short enough to read in seconds, that names the person and makes questions easy to ask. That is the job of a user story.
021 min
Where user stories came from
The fix came from a payroll project, not from a product company. Kent Beck introduced user stories in 1997 on the Chrysler C3 project in Detroit. A year later Alistair Cockburn visited the project and described a story as a promise for a conversation.
The idea was given a structure in 2001. Ron Jeffries proposed that a story has a card that holds the idea, a conversation between the people involved, and a confirmation that the work is done.
Mike Cohn says the pattern began with the agile coach Rachel Davies at Connextra, a company in the UK, in the early 2000s. Bill Wake added a checklist for judging stories in 2003, covered below.
The project where stories began
C3 stood for Chrysler Comprehensive Compensation, a payroll system. Development of C3 began in 1994, with the aim of running payroll for 87,000 employees by 1999. Beck was brought in during 1996 because the system had not yet printed a single paycheck. The team then adopted the practices that became extreme programming, or XP, a method that plans, builds and tests software in very short cycles. The system launched a couple of months after its one-year delivery target. The delay came from unclear business requirements, which is the kind of unclear need that a short card and a conversation are meant to resolve.
032 min
How user stories work: card, conversation, confirmation
User stories work in three parts, and the delivery team shows each of them. This time the product manager writes the request on a card.
As a customer with a booked delivery, I want to move it to another time slot, so that I do not have to phone support.
The card is the first part. It holds the idea and nothing more, because the details are not decided yet. Mike Cohn warns teams against treating the written sentence as the whole requirement: it is a reminder, and the full requirement comes out of the conversation that follows.
The conversation is the second part. The product owner reads the card aloud, and the developer asks what happens when the slot is already full. They agree that a customer can pick only slots that still have room, and that a delivery can be moved until the order is packed. The developer now knows more than any specification line would have told them, and the product owner learned about the full-slot case before it reached a customer.
The confirmation is the third part: the checks that show the story is done. The next section covers it.
| Part | What it is | Who takes part | In the delivery example |
|---|---|---|---|
| Card | A short written reminder | Whoever raises the need | The one-sentence note above |
| Conversation | Talk that fills in the details | Product owner, developer, tester | What happens when the slot is full |
| Confirmation | Checks that show the work is done | Product owner and tester | A customer moves a delivery and the new slot appears on the order |
042 min
How to write a user story sentence
A user story card is easiest to write when it follows one pattern: as a role, I want a goal, so that a benefit. The delivery card above uses it. Each part answers one question.
| Part | Question it answers | In the delivery example | Common mistake |
|---|---|---|---|
| Role | Who needs this? | A customer with a booked delivery | Writing "the system", or "user" with no kind of user |
| Goal | What do they want to do? | Move the delivery to another time slot | Naming a screen or a control instead of a goal |
| Benefit | Why does it matter to them? | So that I do not have to phone support | Leaving it out, or repeating the goal |
Keep the solution out of the goal. "I want a dropdown of times" decides the answer before anyone has talked. "I want to move my delivery" leaves the team free to choose a dropdown, a calendar or something better. Chris Matts proposed putting the benefit first, "in order to" before the role, so the team starts from the value.
The roles and goals come from people, not from the team's imagination. User interviews with customers, and conversations with the support staff who hear from them, produce most of the cards. A persona, a profile of a typical user, can supply the role. Customers rarely say exactly what they need, so listen for the goal behind the request.
A template filled in without thinking
A pattern does not make a good story. In a 2016 study of how practitioners use stories, a developer who disliked them said business people use the template to repackage an old requirement. Cohn gives the same warning: the template is a thinking tool, not a guarantee. A quick test is to cover the "so that" clause. If nobody would notice it gone, it was filler, and the story is still the old requirement.
052 min
How a team confirms a user story is done
A user story card also needs a way to show it is finished. The team writes acceptance criteria: a short list of outcomes that works as a checklist for the work. For the delivery card, the product owner and a tester write them before building starts.
- A customer can pick only slots that still have room.
- A customer can move a delivery until the order is packed.
- The new slot appears on the order page.
- The old slot becomes free for other customers.
Criteria stay few, and each one can be checked by someone who did not write the code. They are usually kept on the back of the card or under the ticket.
Acceptance criteria on a government service
The UK government sets out this practice in its service manual. The UK government's service manual says teams building a service must use user stories. Its example for the Register to vote service lists three outcomes: the user knows how to register online, the user knows how to download a form to register by post, and the user knows where to send the form. None of them names a screen or a button. Each one is something a person can check by asking whether the user now knows it.
Writing criteria as scenarios
Some teams write each criterion as a scenario. Dan North described the form of these scenarios as a starting situation, an event, and the outcomes that must follow. His example was a story about taking cash from a cash machine, which needs two scenarios. In the first scenario the account is in credit, the customer asks for cash, and the machine debits the account, dispenses the cash and returns the card. In the second scenario the account is overdrawn past its limit. The same request now shows a rejection message, dispenses no cash, and still returns the card.
Both scenarios share the same event and some outcomes. They differ only in the starting situation, and that difference is why the story needs both.
062 min
INVEST: what makes a user story good
A user story can have clear criteria and still be hard to plan. Bill Wake gave teams a checklist for that in 2003, and named it INVEST after its six letters.
| Letter | Quality | What to check |
|---|---|---|
| I | Independent | Can the team build it before or after the other stories? |
| N | Negotiable | Does it state the need and leave the details to talk? |
| V | Valuable | Would a customer notice the result? |
| E | Estimable | Does the team understand it well enough to size it? |
| S | Small | Is it at most a few person-weeks of work, and for some teams a few days? |
| T | Testable | Could someone write a test for it? |
Negotiable matters most for the conversation. A story is not a contract for features, since the customer and developer work out the details while they build.
Slice across the layers
Say the delivery team splits the card into three jobs: change the database, build the service, build the screen. None of them is useful alone, and the customer can use nothing until the last one is finished. Wake advises splitting a large story across all the technical layers, so that each piece works from the screen down to the database. Cohn's checklist asks the same thing: has the team avoided splitting a story only by technical layer?
Smaller stories, better estimates
Size also affects planning. When a developer says a story will take more than a month, it often means they do not yet understand what it involves. Wake notes that smaller stories tend to give more accurate estimates.
Splitting has a cost
Wake also warns that split stories must be put back together to deliver the full functionality. Splitting is worth it when it separates high-value parts from low-value ones, so the team can drop or delay the low-value part. Splitting a story into pieces that all must ship together only adds cards.
071 min
How user stories feed the backlog and sprints
Once stories pass that check, the team has to decide which to build first. Teams keep the cards in a product backlog, an ordered list of what to build next. They move the most valuable cards into the next sprint, a work cycle of fixed, short length.
To size a card, many teams give it story points, a number from the Fibonacci sequence: 1, 2, 3, 5, 8 or 13, with 1 for the simplest story. Points rank stories by relative effort and do not stand for hours. A very large story is called an epic. It waits in the backlog until the team has split it, and related stories can be grouped into a theme.
A long, flat list has a weakness: the team cannot see the product as a whole. Jeff Patton found that a story map keeps a team focused on the whole product instead of one story at a time. His map arranges the stories under the activities that users go through, so the team sees the full journey before arguing about one piece.
082 min
Where user stories do not work well
User stories have limits that the teams who use them should know.
Needs that no user asks for
Stories rarely include performance or other non-functional requirements, which are the qualities a product needs apart from its features. So tests such as response time can be overlooked. A team fixes this by adding such needs as acceptance criteria, or as their own cards. Work with no end user at all, such as moving a database, fits a story badly, and most teams write it as a plain task.
The conversation needs a person
The second part of a story depends on someone who knows the business and has time to talk. At C3, the customer representative, a key role in XP, resigned from burnout and stress a few months after launch and could not be replaced. Without that person, a card goes back to being a vague sentence that developers must guess at.
The evidence is thin
The Wikipedia article on user stories says there is no good evidence that they raise software success or developer productivity. The strongest study found is a survey. Lucassen and colleagues collected 182 survey responses from practitioners and held 21 follow-up interviews. Respondents agreed that stories, the template and INVEST improved their own productivity and the quality of their work. That is opinion, not a measured outcome, and respondents who used INVEST were more positive, which could mean INVEST helps or only that careful teams like both. Treat the benefits as likely and unproven.
092 min
User stories vs. nearby concepts
Several other documents sit close to user stories and get mixed up with them.
| Concept | What it is | What separates it from a user story |
|---|---|---|
| Use case | A description of the interactions between a system and the people or systems that use it | A use case lays out the interaction up front. A story is a reminder, and the detail comes from conversation. |
| Persona | A profile of a typical user | A persona says who the person is. A story says what that person wants to do. |
| Jobs to be done | The progress a person wants to make in a situation | A job starts from the situation. A story starts from a role and a goal. |
| Requirements specification | A full written list of what a system must do | A specification tries to be complete. A story is deliberately incomplete until the team talks. |
| Task | A unit of technical work | A task is work for the team. A story is an outcome for a person. |
If the question is what a person needs done, write a story. If the interaction itself must be documented step by step, such as for a safety review, write a use case as well. Teams that gather requirements and constraints often use that work as the input for their first stories.
101 min
How to run user stories this week
A team can start with user stories in one working week. The result is a ranked backlog of cards, each with a few criteria.
- List who uses your product, as kinds of people. Use your personas if you have them.
- Talk to two or three of those people, or to the support staff who hear from them.
- Write one card for each goal, in the pattern: as a role, I want a goal, so that a benefit. Delete any word that names a screen or a control.
- Check each card against INVEST. Split anything that is more than a few weeks of work, and split it across the layers.
- For each card you will build next, hold the conversation with a developer and a tester. Write three to five acceptance criteria on the back.
- Order the cards by value, and size them in story points.
You need index cards or a spreadsheet. When there are many cards, the UK government's service manual suggests a digital tool such as Trello or a spreadsheet. Run the first conversation before you finish the whole list, because the first conversation shows whether the cards are too thin or too large.
?3 questions
Questions people ask
Who writes user stories?
Do user stories replace documentation?
Can user stories be used outside software?
§12 sources
Sources
Wikipedia. User story.
Wikipedia. Chrysler Comprehensive Compensation System.
Jeffries, R. Essential XP: Card, Conversation, Confirmation.
Cohn, M. User Stories: What They Are, How to Write Them, and Examples. Mountain Goat Software.
Show all 12 sourcesShow fewer sources
Cohn, M. User Story Template: What It Is and Why It Works So Well. Mountain Goat Software.
Wake, B. (2003). INVEST in Good Stories, and SMART Tasks. XP123.
Wake, B. Twenty Ways to Split Stories. XP123.
GOV.UK Service Manual. Writing user stories.
North, D. Introducing BDD.
Lucassen, G., Dalpiaz, F., van der Werf, J. M. E. M., & Brinkkemper, S. (2016). The Use and Effectiveness of User Stories in Practice. REFSQ 2016.
Patton, J. The New User Story Backlog is a Map.
Agile Business Consortium. What are User Stories?
