A Guide To Writing Effective User Stories
How To Build What Your Customers Want
In this guide, I’m going to show you how to write great user stories that get software teams working together to build the things your customers want.
What is a user story?
A short description of a feature told from a user’s perspective.
They are short, they are not a technical spec, but most importantly, they are from a user’s perspective.
At this point, it’s important to ask “Who are our users?”. Do you know them? Does the whole team, including developers know them? You’re likely to have many user types, all with different desires and needs.
If you don’t know your users you should not write user stories.
If your team needs help getting to know your users, you could consider using personas. Here’s a great guide to creating and using personas.
The most important aspect to a user story to me, is that it’s a collaboration tool. Ron Jeffries had a similar outlook, coining them as:
“User stories are a promise for a conversation”
They shouldn’t be handed to a dev team. They should prompt a conversation across the whole team. It’s everyone’s responsibility to understand what they are building and why. If you’re using Scrum, the backlog refinement is a good time to write your user stories together.
Why should we care?
I believe that writing good user stories results in not only better customer satisfaction but also better employee/contractor satisfaction.
Badly written user stories can lead to confusion, they lead to the wrong things getting developed, that leads to wastage and delays, all of which lead to frustration for the whole team.
Working with user stories is easy but writing effective ones is hard.
How do we write effective user stories?
There are 5 guiding principles that I recommend following:
- Everyone should be happy
Getting everyone on board is important, so get everyone who’ll be writing and using your user stories to input their ideas and agree on the format you’ll all use. - Be consistent
Once you’ve got an agreed structure, make sure you stick to it. - Focus on what’s important
When you’re writing them out, avoid any unimportant details. Take the time to make them concise, remove any waffle as it just gets in the way. - No implementation details
Always focus on the “why” not the “how”. Why does a user want something, not how are we going to build it. If you need to provide technical details these should be attached as separate spec file. - Clear, feasible & testable
Make sure everyone can understand each story and that it’s achievable in the time-frame you’re happy with. If you’re delivering in 2 week sprints, then it should not take any longer than those 2 weeks.
User story anatomy
There are 3 mandatory parts to a user story, the title, description and acceptance criteria. Your team may agree that a user story must have other fields before work can start on it. For example, you may require an assignee, story points or the business impact, but I consider these to be optional as not every organisation will require these.
Title
Titles should be short, unique and not misleading.
Some good examples:
- “Add contact us panel to home page”
- “Add debit card support to shopping cart”
- “Update email template tagging”
Some less good (sadly real world) examples:
- “Make agreed changes”
- “32072 — Updated Mapping- Upsell User story (27263)”
- “Links — tracking query string for bill trigger and smart post install …”
Description
The description holds the real power of the user story. It should create empathy in the team for the user and an understanding of the problem to be solved.
A very popular structure for the description takes the form of “As a … I want … so I can …”.
This structure prompts the question of “as a who”? Who is the user facing the problem? You could reference a persona here if you’re using them, alternatively, give the user a name and add some context to the user’s situation. Try to avoid using “As a customer” or “As a user” as this is less effective at creating empathy for an actual user.
The description should be written in simple, clear language, without technical terms, or abbreviations. You should ask yourself “Can your Nan understand it?” A new team member should be able to read the description and understand exactly what the problem is that needs to be solved.
The following real examples are taken from a project to add functionality to an online account system for customers of a UK energy company.
Some good examples:
- “As John, a customer with a traditional electricity meter, I want to understand why I can’t see charts of my energy usage in any more detail than month by month so I can decide whether I want to change this and get a smart meter installed.”
- “As Bart, a proactive traditional meter customer wanting to make sure my next bill is accurate, I want to know if a meter reading has already been submitted today and that I don’t need to submit another.”
Some less good examples:
- “As a user I want to prevent trad customers from being able to drill down below the highest level so that their customer experience is managed”
- “As a customer who has either provided a meter read today or had a fuel read estimated today, I should not be allowed to submit another meter read today as SAP cannot accept more than one meter read per fuel per day.”
The less good examples were actually rewritten to be the good examples above as the problems they outlined were not clear. This refinement process should be done any time any part of a user story is not clear. Just make sure everyone in the team is aware and agrees to the changes.
Acceptance criteria
Acceptance criteria are used to prove the completeness of the user story. This is helpful to developers and testers.
Writing the acceptance criteria is an effective way of going through all the detail of the story before starting any work. Many potential pitfalls or unexpected work can be “discovered” early by writing good acceptance criteria.
A very popular structure for the acceptance criteria takes the form of “Given… When… Then…” as seen in the examples below.
If a user story has more than 10 acceptance criteria, it may be an indication that the story is doing too many things. In this case, I recommend considering splitting the story up.
The whole team should be involved in the writing of the acceptance criteria. If this is not possible, I highly recommend everyone reads and agrees to them before working on them. This is especially true of anyone involved in testing the work.
Numbering the acceptance criteria makes it easy to reference them.
Some good examples:
- Given a customer with a traditional meter on the energy usage bar chart
When clicking on the tool-tip for a month
Then a popup is displayed matching the specified design. - Given a dual fuel customer viewing the energy usage bar chart
When they have months with estimated values
Then the chart legend should clearly show an estimated electricity icon with a light red bar
Then the chart legend should clearly show an estimated gas icon with a light blue bar.
When we don’t need user stories
Technical tasks
Sometimes a technical task doesn’t seem to relate to a customer. If this is the case, don’t use a user story. But it is always worth considering why you are doing a technical task; are you upgrading a library to improve the speed for users? If so, that should be a user story.
Bugs
If a bug is found during the testing of a user story currently being worked on, then it should be associated with that user story.
If a bug is found for something that is not a current user story, then it should not be associated with a user story but added to the backlog as an independent task.
Continuous improvement
User stories will evolve as more is learnt about the work to be done. This is good, continue to improve them right up to the point you release the work to users. Just make sure everyone on your team is aware and agrees to any changes being made.
Keep refining the process. Be agile, reflect on how your user stories are working for your team, discuss them in retros and keep improving the way you write them.
