Topics3 of 5: Writing a good story
Writing a good story
A user story is a short description of something a person needs, written so the whole team understands who it is for and why it matters. This guide covers the format, the description, acceptance criteria, the Definition of Done, and a worked example.
10 min readUpdated
On this page9 sections
The story format
Most teams write the summary of a story as one sentence:
As a who, I want what, so that why.
- Who: a real kind of user, such as “a support agent” or “a first-time buyer”. Avoid “a user” when you can be specific.
- What: what they want to do, not how the screen should look.
- Why: the benefit. It is the part teams skip, and the part that lets developers suggest a better way to get there.
The sentence is a reminder of a conversation, not a full specification. The details come from talking, and then go into the description and the acceptance criteria.
A good description
The description gives someone the context to pick up the story without a meeting. Keep it short, and link to anything long.
- Context: what happens today, and why that is a problem.
- Scope: what is in, and what is explicitly out.
- Links: designs, the support request, the parent epic.
- Open questions: anything still to agree, and who will answer it.
Acceptance criteria
Acceptance criteria are the conditions this particular story must meet for the Product Owner to accept it. They make “done” testable for this piece of work, and they are agreed before work starts, usually during refinement.
Style 1: Given / When / Then
Good for behaviour with clear steps. Each scenario names a starting point, an action and the expected result.
When I choose “Forgot password” and enter my email address
Then I see “Check your email” and receive a reset link within a minute
Style 2: Checklist
Good for rules and limits that are not a sequence of steps.
- The reset link works once, and expires after 30 minutes
- The page shows the same message whether or not the email has an account
- The new password must follow the existing password rules
Use whichever reads more clearly. Many stories mix both.
Definition of Done
The Definition of Done is the team’s shared quality bar: a checklist that applies to every work item before it can be called done. It does not change from story to story. A typical one:
- Code reviewed by another developer
- Automated tests written and passing
- Works on phone and desktop browsers
- Keyboard and screen reader checked
- Deployed to the staging environment
- Help text or release note updated
Scrum treats the Definition of Done as the gate into the increment. Work that falls short of it stays out: nobody ships it, nobody demonstrates it at the Sprint Review, and the item goes back on the Product Backlog for a later sprint.
The Scrum details on this page summarise The Scrum Guide (2020) by Ken Schwaber and Jeff Sutherland, in our own words. The Guide is licensed CC BY-SA 4.0; read it at scrumguides.org.
Acceptance criteria vs Definition of Done
They are easy to mix up, because both are checklists that decide whether something is done.
| Compared | Acceptance criteria | Definition of Done |
|---|---|---|
| Applies to | One story | Every work item |
| Answers | “Did we build the right thing?” | “Did we build it properly, and finish it?” |
| Written by | The Product Owner with the team, during refinement | The whole Scrum Team, or the organisation’s standard |
| Changes | Every story has its own | Rarely; it grows as the team improves, usually at a retrospective |
| Example | “The reset link expires after 30 minutes.” | “Automated tests written and passing.” |
A quick test: if a line would be true for every story, it belongs in the Definition of Done, not in the acceptance criteria.
INVEST: a check for good stories
INVEST, coined by Bill Wake in 2003 in “INVEST in Good Stories, and SMART Tasks”, is a six-letter checklist for a well-formed story. The meanings below are ours.
A worked example
Here is one complete story, as it might look in a team’s backlog.
Reset a forgotten password from the sign-in page
As a returning customer who has forgotten my password, I want to reset it from the sign-in page, so that I can get back into my account without contacting support.
Today, customers who forget their password have to email support, which is slow for them and for us. Out of scope: changing the password rules, and signing in with Google. Designs are linked in the epic.
When I choose “Forgot password” and enter my email address
Then I see “Check your email” and receive a reset link within a minute
When I ask for a reset link
Then I see the same “Check your email” message
And no email is sent
- The link works once and expires after 30 minutes
- After a reset, I am signed out on every other device
- Ticked: Code reviewed by another developer
- Ticked: Automated tests written and passing
- Ticked: Works on phone and desktop browsers
- Ticked: Keyboard and screen reader checked
- Deployed to the staging environment
- Help text or release note updated
Notice that the acceptance criteria are about this story only, while the Definition of Done list is the same on every work item.
Common mistakes
- A task dressed up as a story.“As a developer, I want an API endpoint…” describes a step, not a need. Write the user’s need, and list the technical steps as subtasks.
- “As a user” everywhere.Name the kind of user. A support agent and a first-time buyer need different things.
- No “so that”.Without the reason, nobody can suggest a simpler way to reach the same goal.
- Acceptance criteria that repeat the Definition of Done.“Code is reviewed” is true for every item. Keep the criteria specific to this story.
- Criteria that sneak in new scope.If a criterion adds a feature, it is a new story. Write it separately and let the Product Owner order it.
- Too big to finish in one sprint.Split it by step in the workflow, by rule or by kind of user, and ship the simplest path first.
How ScrumTeam helps
Write stories where the team works on them.
- A description and a separate acceptance criteria field on stories, epics and bugs, with a Given / When / Then prompt
- A Definition of Done checklist for each project’s workflow, ticked on every work item
- A warning and a confirm before an item with unticked Definition of Done items moves to Done
- Six work item types, including Story, Subtask and Spike, with Epic › Story › Subtask nesting
- Story points, and sprint planning that shows capacity and the team’s average velocity