How to Write a Good User Story: with Examples & Templates
Writing requirements for a software project without a structure is a complete nightmare. Anyone who's worked on the development side of building a digital product knows that the biggest challenge isn't building the thing; it's knowing what to build.
Like everything else in software development, there's a scientific, systematic solution to this problem; the user story. A user story is a syntax of defining a requirement that's become the incumbent in software development because it both the business and developers understand what's required.
I've probably written more than 10,000 user stories. Still, whenever I take a break for a few months, I find myself browsing Google looking for examples of stories to see if I can strike up some inspiration of how to handle the trickier stuff (like authentication, project setup, design tasks, etc).
Every time I go looking, I end up on Reddit where the answers usually follow the theme of "no one would share actual user stories because they're legally protected" - which isn't true. It's just that user stories are boring, and no one has bothered to make Google index an article actually dedicated to story examples... until now :).
I'm sharing some examples of actual stories I've written recently, along with the behaviour-driven-development acceptance criteria my team uses to make sure that everyone understands the requirements and acts as a baseline for our automated testing.
What is a user story? Our definition
A user story is a vehicle for describing a system feature that follows a particular syntax. Even though it's technically possible to write a story without following this syntax, it wouldn't really be a proper user story.
Here's the user story syntax:
As some kind of user,
I want to perform an action,
so I can achieve an outcome.
The idea behind this formula is to answer the biggest questions that developers have when they start building the feature.
Which user are we working with? Is it an administrator, a user with restricted permissions, or someone who shouldn't even have access to the system?
What does the user want to do? From the user's perspective, what are they trying to do? The important distinction here is the question isn't asking, "how should this feature work". Requirements should be agnostic of implementation suggestions.
Why do they want this? Sometimes it's hard to understand how a feature should work simply by knowing what the user wants to do. Having the additional context to understand why they want to do something can let developers create a better-fitting solution.
Pros of using stories
User stories can feel tedious to write out, but they bring tangible benefits to the organisation and management of a software project.
Remove assumption
The biggest problems with application development projects usually come from making assumptions. Assumptions aren't limited to how the developer implements a feature; they're also made by the product owner (or client) on what's feasible.
Define intent
Without including the "so I can achieve an outcome" part of a user story, it's just a vague request that may not be the best way to achieve the outcome. Knowing the intention of a requirement helps get the product owner and development team on the same page.
Standardised requirements
Without a structure to stick to, requirements tend to take the easiest and sloppiest form. It's rarely consistent or detailed enough to figure out what needs to be done. Dealing with a large number of requirements that don't follow the same structure or approach is an absolute nightmare.
Provides stakeholders with a way to communicate
Stakeholders who are working with a development team rarely know how to think through their requirements fully or communicate them eloquently. User stories give them a concrete approach for explaining what they want.
Cons of user stories
User stories on their own don't really have "cons" or "disadvantages". The problems come from their implementation.
They're easy to write poorly
It's easy to accidentally write a user story the wrong way, so it doesn't communicate the business's need. For example:
As a user,
I want to implement a form plugin,
So I can have a working form.
From a developer's perspective, this doesn't get you any closer to understanding what the customer wants. The requirement is coloured with technical implementation details. If the best possible solution isn't to use a form then the development team can only achieve this requirement through a sub-optimal implementation.
Customers often find themselves writing user stories, especially if they're going to market to get developer quotes. Without some understanding and practice, the requirements end up needing to be rewritten down the line.
The format can feel repetitious and tedious
A big application can require hundreds of user stories. If there are only one or two user types, then starting every single story with "As a user..." can feel
Stories aren't complete without additional detail
User stories are a conversation placeholder and aren't intended to have all the details required for a developer to start building a new feature. That part needs to be handled during a sprint planning session or technical review.
To get the most out of our user stories, there needs to be well-defined conditions for completion and examples of how the story should work. This is where acceptance criteria and behaviour-driven development scenarios come in handy.
What makes a good user story?
A good user story doesn't necessarily need to follow the regular syntax, despite what a lot of die-hard agile project managers will argue.
To be useful and complete, a good user story need to:
- Covers a description of the feature to be built
- Avoids any description of how the feature should be built (i.e. technology)
- Explains the value to the end user
- Has an outcome that can be measured and achieved
- Consistent
- They're testable
A lot of teams, including ours, will start writing user stories in a slightly different format. However they're written, the story always needs to inform both parties of what's required and have a clear way of being achieved.
Behaviour-driven development scenarios
Before we get to the user story examples, it's worth talking through the other methodology we use to expand on the information available for the developers. User stories by design, are supposed to be concise and indicative. The developers and designers implementing the story will have plenty of questions that need to be answered.
Behaviour-driven development is an approach of documenting requirements with examples. It follows a similar syntax to user stories:
GIVEN some condition has been achieved
WHEN a trigger event happens
THEN a result will be achieved
The idea is to document a few primary examples of how a feature (or user story) will be used. Providing actual examples not only acts as a great way to get everyone agreeing on how it should work, it also makes the product team think through the edge cases and creates tests that need to be passed for the feature to be considered complete.
Agile user stories examples
Finally, on to the actual examples. I've anonymised and sanitised these stories and scenarios a little to avoid making any of our clients upset.
These stories would typically have a handful of acceptance criteria too for peripheral behaviours like confirmation or validation messaging. To avoid making them too hard to read through, I've left these out.
---
Feature: Marking invoices complete.
Story: As an administrator, I want to mark a job as invoiced, so it can be recorded and reconciled with accounting.
Scenario 1: A job is completed and marked as invoiced
GIVEN I'm logged in as an administrator
AND I've completed a job
WHEN I mark the job as invoiced
THEN the UI will show the job as invoiced
AND the job status will change to invoiced
Scenario 2: A job is not complete and marked as invoiced
GIVEN I'm logged in as an administrator
AND a job has outstanding tasks
WHEN I mark the job as invoiced
THEN I will receive an error message that says, "Job can't be invoiced until all tasks are completed"
---
Feature: Carpenter marks installation as complete
Story: As a carpenter, when I've finished my installation, I want to mark it complete so everyone else on the team knows it's done.
Scenario 1: The carpenter marks the job as complete, and job status changes
GIVEN I'm logged in as a carpenter
AND I've finished an installation
WHEN I mark the job as complete
THEN its status will change to "installed"
Scenario 2: An administrator wants to know if a job has been installed yet
GIVEN I'm logged in as an administrator
AND I want to know if a job has been installed
WHEN I open the job
THEN I can see it's status is "installed"
---
Feature: Staff unavailability
Story: As an administrator, I want to see a list of upcoming days when the staff are unavailable, so I can resource and plan efficiently
Scenario 1: An administrator wants to check who took holidays last month
GIVEN I'm logged in as an administrator
WHEN I view past staff unavailability
THEN I can see a list of all staff holidays that are in the past
Scenario 2: An administrator wants to check if a staff member has any upcoming holidays
GIVEN I'm logged in as an administrator
WHEN I view upcoming staff unavailability
THEN I can see if a staff member has an upcoming holiday registered
---
Feature: Calendar rolling date
Story: As an administrator, I want to easily scroll up and down the calendar to see past and future dates, so I can plan my team's workload efficiently
Scenario 1: An administrator wants to schedule a job 4 weeks in the future
GIVEN I'm logged in as an administrator
AND I want to schedule a job in 4 weeks time
WHEN I scroll down the calendar
THEN new weeks will display
Scenrio 2: An administrator wants to check how many jobs were done last month
GIVEN I'm logged in as an administrator
AND I want to see what work was completed last month
WHEN I scroll up on the calendar
THEN I can see all the jobs that were scheduled and completed
---
Feature: Discourse Single Sign On
Story: As a user, I want to sign into Discourse using the same credentials I use for the app, so I can see my forum posts and comment history
Scenario 1: A user wants to add a comment on the integrated Discourse forum
GIVEN I'm logged in as a user
AND I open the integrated Discourse forum
WHEN I leave a comment
THEN I will be successful without having to sign up for a new account
Scenario 2: A user wants to view their forum post history through Discourse
GIVEN I have an active application user account
AND I've left comments on the forum in the past
WHEN I log into Discourse
THEN I can use the same credentials I use for the application
AND I can see my forum comment history
---
This is a decent cross-section of user stories and scenarios to get you inspiration moving.
How to Write User Stories: Our Workflow
The last thing to explain is our full process for building user stories. Achieving a full coverage of stories can be tricky and it's easy to miss things at the start of the project.
At the start of every project, we run a Product Roadmapping session with our clients, consisting of a handful of 2-hour meetings. One of the goals of the sessions is to understand and document the major user workflows. A workflow is a user's steps to achieve their goal.
Because workflows are less granular than stories, capturing them in totality is easier. Once you've got all the workflows, then you can move forward to breaking the workflow into the individual stories. Then the stories are decomposed into scenarios and acceptance criteria!
Wrapping up
Hopefully, this breakdown of how we write user stories, along with a handful of actual examples, has helped you on your journey. If you have questions, please leave a comment below, and we'll get back to you in a few business days.
