Your Guide to User Stories and Acceptance Criteria
If you are familiar with software, app or website development, you may have heard of User Stories and Acceptance Criteria.
If you are looking to start work on an Agile project and you feel that you need a primer on User Stories and Acceptance Criteria then this article is for you. This article will give you the essentials for both User Stories and Acceptance Criteria, but let's start by getting familiar with User Stories.
What is a User Story?
Wikipedia has this to say about User Stories:
In software development and product management, a User Story is an informal, natural language description of one or more features of a software system. User stories are often written from the perspective of an end user or user of a system.
In other words, in Agile projects, User Stories are a powerful way of describing and encapsulating what a user needs from one part of a system and why. They should be the result of conversations with several stakeholders to ensure the needs truly reflect that of the user.
You may also have heard of Epics. These are large User Stories that would be too big to deliver in a single iteration. When you have an Epic, it is best to break them down into smaller User Stories, so that they are achievable in Sprints (a time-boxed allocation of development).
Why User Stories?
Before we delve into how a User Story is structured, let’s explore some of the benefits they provide.
User Stories have a lot of practical benefits for any Agile project. In fact they are fundamental to Agile project methodology. Here are some reasons why:
- They keep the focus on the needs of the user.
- They illustrate how the completed feature will provide value to a user.
- They provide a shared understanding of a feature set to all team members and stakeholders.
- They help to get stakeholder agreement for a particular feature.
- They help teams to provide more accurate estimates.
- They help teams to prioritise features to be delivered next.
- They promote creativity within the team when finding a solution for the User Story.
- Due to their bite size nature, they inspire momentum due to the team achieving small regular wins.
- They can be written by any member of the team who has enough understanding of the user requirements.
- Systems like Jira are built to manage the flow of User Stories within Agile projects.
User Story Formats
OK, so we have looked at why User Stories are useful, but what do they look like?
There are a number of different User Story formats, often called templates, but I personally like the Connextra template, which is the original and is still used widely today.
It is straight forward and can be broken down to the following elements:
As a [user type],
I want [a particular feature ]
So that [I get some benefit].
An example User Story using this format may be:
As an [Editor], I want [to review articles before they are published] so that [I can find and correct errors in spelling, punctuation, and tone].
Another way to look at this format is to break User Stories into who, what and why:
[Who] wants the new functionality?
[What] do they want added or changed?
[Why] do they want it?
User Story Elements
Let’s dive into the who, what and why of User Stories to explore these elements in more detail.
This element usually starts with, “As a…
A lot of User Stories actually start with, “As a User… This is often considered too broad, however there may be some User Stories that are shared amongst all user roles. Usually though, it is helpful to categorise the user of the system into specific roles.
This helps provide some context around the type of functionality that is being specified. For instance, a power user of a system would be needing advanced functionality, whilst a new user would be looking for basics so they can start using the system. By using actual roles, it frames the User Story with familiarity and contextualises the need outlined in the next step of the User Story.
For instance, an Editor evokes editing functionality, an Admin suggests someone who has administrative rights to a system and a Job Seeker is obviously looking for employment. If we described these roles as a User then we would automatically lose that contextual understanding.
Let’s start putting a User Story together with a working example:
As an [Editor]...
Another recommendation is to use personas, as you are able to frame User Stories so that they solve a particular pain point the persona may have or perhaps there is an identifiable need or behaviour that you may have uncovered about them during research.
As personas should be based on qualitative and quantitative data acquired through user research, User Stories can be crafted with the confidence that the functionality being specified is actually needed by the particular role.
This is the element of the User Story that describes what is needed or required by the user.
This section of the User Story often starts with, “I want… which is often fine, however this should really only be used if the user genuinely wants the functionality.
For instance, what if the specific role is required to use the functionality to gain certification for their job? That is more of a need or a requirement. So this element of the User Story may have several ways of starting such as:
- "I want"
- "I need"
- "I require..."
You then describe the functionality that is needed by the user described in the first step. Below is our example User Story, now with the second element in place describing what the editor wants:
As an [Editor], I want [to review articles before they are published...]
The third and last element of the User Story, puts context as to why the user wants the new functionality.
This element of the User Story generally starts with "so that..."
This is important as it helps the team working on the project to better understand the problem and to then provide a solution that suits the need or want of the user.
Another reason for this last element is that it shows the level of value attributed to the User Story. When prioritising work to be undertaken during a sprint, this last element of the User Story is major consideration when evaluating business priorities.
Some characteristics of Acceptance Criteria are:
They should set out what is an acceptable level of completion.
They should be testable.
They must be understandable.
They must be measurable
They should be based on the particular users’ needs or wants.
They should have an agreed understanding by stakeholders for what constitutes criteria that is deemed acceptable.
They should be clear and concise.
Acceptance Criteria is typically formatted with either the Given/When/Then format or as a checklist of requirements.
The Given/When/Then format, is a scenario driven Acceptance Criteria derived from Behaviour Driven Development (BDD) and generally consists of 5 parts:
Scenario – This is the name of the particular Acceptance Criteria. You can have multiple scenarios associated with a User Story – if that is the case, it is useful to number them.
Given – This is the starting state of the scenario and gives context to the Acceptance Criteria.
When – This is the particular event that may occur or an action that the user may make in the scenario.
Then – This is the outcome of the scenario once the event has occurred.
And – This is used to extend any of the Given/When/Then statements.
Adding it after the Given statement would provide more context, however Given statements should be as succinct as possible to avoid distractions;
Adding it after the When statement would provide additional event criteria, but again it is usually better to have one When statement per scenario; and,
Adding it after the Then statement would provide additional outcomes.
The best way to explain this is to show how Given/When/Then fits into our ongoing example. You will notice that the And statements are indented, which is a formatting technique to assist in showing where any of the statements are extended.
As an , I want so that .
Scenario 1: Editing an Article
Given [the editor is reviewing a submitted article.]
When [the editor selects some copy that needs changing.]
And [changes the selected copy using a keyboard.]
And [saves the article.]
Then [the article will be updated to include the saved changes.]
And [a history tab will show the history of edits made to the article.]
And [the contributor who submitted the article for review will be notified of the change via email.]<
Checklist of Requirements
Sometimes the Given/When/Then format may not work for what you are trying to define and a simple checklist of requirements may be more suitable. /p>
The checklist format uses a list of pass/fail statements that are required to be met before the User Story is considered complete. If you like a more straight forward set of criteria then this approach may be for you, however both options are viable formats.
Let’s put this into our ongoing example: <
Editing an Article
Articles can be submitted for review by a contributor.
Articles can be reviewed and edited by an editor.
Text can be highlighted and changed by an editor.
The article can be saved so that any edits made are now included in the article.
When the article is saved, the contributor will be sent an email notifying them of the changes.
The contributor can view the updated article.<
The editor and the contributor can view a history tab to see what changes were made and when.
This has been my introduction into the world of User Stories and Acceptance Criteria. I hope this primer has proven to be useful and that you can start using this methodology in your next Agile project. If you are interested in learning more about Agile methodology, we have a free Outsourcing and Agile Development - 6 Critical Success Factors whitepaper that provides some key learnings.
Speedwell has a discovery team well-versed in Agile delivery and User Story / Acceptance Criteria definition. If you need any assistance in this aspect of your next Agile project, please contact us to discuss your project requirements.
Illustration Sources - The amazing illustrations used throughout this article are courtesy of Katerina Limpitsouni (https://undraw.co).
Is your website designed for an optimal user experience?
From vision to implementation our clients praise us for our well-architected solutions, strategies and UX work that deliver exceptional experiences. We are proud to have a team of Digital Engineers who inspire our clients to innovate.
Rod Blaxell, UX Lead, Speedwell