User stories are a concept from agile software development. They are an informal description of a desired feature and are written from the perspective of a user.
Format
One of the most common formats for writing user stories is the following template:
As a <role>, I want <feature> so that <goal>
There are other templates, but they are similar to the one presented. The template or format is not too important, but using a consistent pattern across stories in a project helps readers quickly get an overview over each story.
Conversations
A user story does not consist of the written description alone, but also includes conversations about the topic. During these conversations, the team members can discuss the story, ask questions and gain a common understanding.
The amount of details to be discussed depends on the people involved and will also differ from story to story. The following factors can be indicators that more detailed discussions might be necessary:
- The story is about a new topic that has not yet been covered by a previous story
- The team has new members or does not have much experience
- Previous similar stories have caused problems
Absence of these factors could indicate that fewer details might be sufficient.
Written documentation
The goal of a user story is to provide as much details as necessary to understand the desired functionality and the motivation behind it. It is not intended to be used as a formal requirement specification, where all possible edge cases are covered.
During discussions, the people involved will learn more details about the user story. Depending on the preferences of the team, these details can be added to the written story description.
Team members that have worked together for a long time could need fewer written notes. When interactions with the story author are difficult, for example due to different time zones, more written documentation can be helpful.
Notes:
- The user needs to enter their password to confirm the deletion
- The account will be deactivated first and deleted after 7 days
Taking notes can help ensure that important information is not forgotten later
When using project management software like Jira or Pivotal Tracker, it can also be helpful to use a short summary for the title (for example Account deletion). That way, stories can be identified quicker, which is especially helpful when organizing a large amount of stories.
Acceptance criteria
A common form of adding more details to the written story description is in the form of acceptance criteria. They describe specific functionalities that need to be fulfilled for the story to be accepted.
Contents
A user story describes the required feature from the perspective of a user. It should usually answer, at minimum, the following questions:
- From which perspective is the story written?
- What is the feature that should be realized?
- What is the actual goal that the user is trying to achieve?
The following sections give more insights into the role, the feature and the goal.
The role
Sometimes it’s enough to choose the role of a user. Most systems, however, have many different users and the role description should be as specific as possible for the particular story.
As a user, I want to be able to change my name so that my profile matches my new name after a name change.
This story does not need any distinction based on roles, as that use case is valid for all users. There is also no reason to believe that the implementation will be different for different roles, so it would not be reasonable to write one user story for each role.
When possible, the role should not be an abstract entity like a company or a customer but an individual person.
As a new customer, I want to see a support phone number so that I can call someone when I need help with the system.
Abstract roles make it harder to identify with the user. Here, as a new user could be chosen instead.
When the requirements are different for different roles, consider writing multiple stories instead of choosing a more general role.
As a user, I want to be able to login so that I can edit my profile.
This story is fine if all users use the same authentication mechanism. However, it’s possible that the login for internal users will be different, for example to integrate with the company’s existing security concept. In that case, the story should be split into two stories to reflect these different requirements.
User segmentation
Distinction of user roles can happen on a technical level, for example based on assigned security roles or permissions.
As an administrator, I want to be able to delete users so that I have a way to remove bots and fake users.
The specific role is needed in this story, as the feature should not be available to regular users.
Users can also be in different roles based on their usage pattern.
As a user with more than 10.000 followers, I want to enable additional security measures so that I have better protection against fraudulent account access.
In this example, the role helps better understand the goal and motivation. During further discussions, the story could be extended to include additional roles with elevated security risks, like journalists or political activists.
Some software system have extended access-control mechanisms with multiple different security roles and privileges. This is especially common in enterprise software.
As an Inventory Controller, I want to get a report of all deliveries that are due today, so that I can easily spot any discrepancies.
When writing user stories for systems with many different security roles, prefer non-technical role descriptions, such as the job title, over a list of security permissions. When described as “a user with access to the stock management system,” for example, readers of the story will have a harder time understanding the user’s motivations.
Distinction of roles can also happen based on abilities (As a visually impaired user, …), culture (As a user of the Arabic script, …), current personal situation (As a parent with a newborn child, …) and various other factors.
Personas
A persona is a fictional character created to represent a group of users that behave in a similar way. It can help achieve better identification with the users and can simplify communication within the team.
The feature
The feature is the main part of the story and describes what functionality is required.
As a user, I want to be able to send direct messages so that I can communicate privately with other users.
The required functionality is described from the perspective of the user.
Scope
The user story should have a clearly defined scope, and the desired feature should not be too abstract.
As an internal auditor, I want to have a full audit log so that I can determine if the processes are followed correctly.
This story is probably too broad. However, it still has value, as it describes the required functionality and gives a motivation. The team could split this story into multiple separate stories to implement the functionality.
Implementation details
The user story should only include details about the functionality that is requested (the what). It should not include any parameters about the way the feature will be implemented (the how).
As a user, I want to have a drop-down list so that I can choose a language.
The feature already includes implementation details. The functionality that is required is given in the last part (choose a language) and the actual motivation is missing.
As a user, I want to be able to choose a language so that I can read the website in a language I understand.
The motivation makes it clear what the user’s goal is and enables team members to come up with adequate solutions, for example detecting the language from the user’s browser.
Technical features
User stories should provide value for the customer. Features that only help with development are not directly useful to end users and should not be described as a user story.
As a tester, I want to have an easy way to reset the database so that I can quickly try out multiple different scenarios.
While the feature itself might be useful to the team, the user story format is not suitable for these types of requirements. They could be written as tasks instead.
The goal
The last part of a user story description explains the why. This is possibly the most important part of a story, as it gives the readers insights into the underlying motivation for the feature.
A well described goal enables team members to provide adequate solutions for the requested feature. It also allows others to assess if the requested feature is actually useful in achieving the goal.
As a user, I want to be able to delete coupons so that I can remove expired coupons and can easier identify valid coupons.
The goal gives enough details to understand the user’s motivation. It enables readers to suggest alternative or additional solutions, such as automatically removing expired coupons or sorting coupons by expiration date.
As a user, I want to be able to register so that I can join the website.
This explanation does not answer the question why users need to register. What is the motivation for the user to join the website? Are there any actions they can only perform when they have an account?
True motivation
When writing the user story, it is important to learn the true motivation behind the feature. Without a clear goal, the team cannot evaluate if the proposed solution will actually help the user.
As a user, I want to have a connection to a third-party weather API so that I can get up-to-date weather data.
This is probably not the true motivation, as it is not clear why the weather data is needed. The user could need the data for accurate predictions of heating energy requirements or crop yields, for example. Providing a clear goal helps the team come up with a suitable solution for the user’s requirements.
As a user, I want to be able to delete multiple emails at once so that I can quickly delete unwanted emails.
The user’s goal is not clear in this story. Maybe the user receives unwanted spam emails and they are looking for a way to quickly delete those messages. However, if that is the actual goal, a better solution could be to automatically filter out spam emails so that the user does not need to delete them manually.
Developer features
When providing features for technical customers, for example plugin developers, motivation can be hard because it is often not known beforehand what the specific feature will be used for. This can be a case where the motivation will be omitted.
As a third party developer, I want to have an API to list a user’s followers.
There are many ways how the API can be used and it is possible that new, unexpected use cases will be discovered once the API is available. The actual goal is not known, so it is omitted in this story.
Basic functionality
Some features are basic requirements for a system. Without them, the whole system is not usable and giving a motivation would be similar to motivating the system itself. In that case, it can make sense to have a discussion or a document which gives an overview of the overarching goal and which can be referenced from the user story.
The same can also be true for a new group of features in an existing system.
As a user, I want to see my account balance.
For an online banking software, displaying the account balance is such a basic feature that it can be very hard to motivate. Referencing a document about the vision for the online banking software might be more useful here.
Further reading
- Cohn, Mike (2004). User Stories Applied: For Agile Software Development