Beta This is new guidance. Complete our quick 5-question survey to help us improve it.
Writing user stories
User stories describe a user and the reason why they need to use the service you’re building.
You must use user stories when building your service - they’re essential to building and running a service that meets user needs.
You should make sure every member of your team writes user stories and uses them to:
- track everything they need to do
- think about their work from a user’s perspective
- discuss their work with colleagues
- prioritise their work
Meeting the Digital Service Standard
To pass point 4 (use agile methods) you need to show how you’ve adopted agile tools and techniques, including working with user stories.
To pass point 5 (iterate and improve frequently) you need to show how you prioritise user stories and move them quickly and smoothly from research to production.
How to write a user story
What to include
Your user stories should include enough information for your product manager to decide how important the story is. They should always include:
- the person using the service (the actor)
- what the user needs the service for (the narrative)
- why the user needs it (the goal)
The right format for user stories
They’re usually written in the format:
As a… [who is the user?]
I need/want/expect to… [what does the user want to do?]
So that… [why does the user want to do this?]
The Register to vote service’s user story is ‘as a UK resident, I want to get my details on the electoral register so that I can vote’.
You don’t have to use this format but you should always briefly explain the actor, the narrative and the goal.
Focus on the goal
The most important part of a user story is the goal. This helps you:
- make sure you’re solving the right problem
- decide when the story is done and a user need is met
If you’re struggling to write the goal then you should reconsider why you think you need that feature.
You can also include a few acceptance criteria for each story. Acceptance criteria are a list of outcomes that you use as a checklist to confirm that your service has done its job and is meeting that user need.
They’re often written as a list that begins with ‘it’s done when…’.
The acceptance criteria for the Register to vote service are the following:
- ‘it’s done when the user knows how to register online’
- ‘it’s done when the user knows how to download a form to register by post’
- ‘it’s done when the user knows where to send the form’
Use the acceptance criteria to link to any evidence (for example spreadsheets or diagrams) that support the story.
Large user stories (ones that would take more than a few weeks to develop and test) are typically called epics. If possible, split a large story or epic into smaller stories that can be completed within an iteration.
How to record user stories
Record each user story on a card and give it a title. The cards can be:
- actual cards posted on your team wall
- digital, eg teams at the Ministry of Justice and the Government Digital Service use Trello and Pivotal Tracker
Planning with your user stories
When you have a lot of stories, you might want to keep them in a digital format (like Trello or a spreadsheet) and then turn them into physical cards as part of planning.
You should put all your stories in your backlog where your product manager will organise them in order of priority. They will then sit in the backlog until your team decides they are ready to work on them.
Your product manager and relevant team members can have a more in-depth discussion about the story when they’re ready to start work on it. You should record more detail from these discussions in the user story.
You may also find these guides useful:
- Published by:
- Agile delivery community
- Last update:
Guidance first published