How to create user stories
Here we will look at how user stories and requirements gathering in software development can prime your digital initiative for success.
Gathering requirements for software development is a vital communication process. There are multiple parties involved and a project relies on customers, users, domain experts, and many others, each with their own view of how the system should function.
We will look at how user stories can help us to gather the information we need for a successful project. For a project to succeed, there needs to be a process in place that gets information as early and often as possible, where decision making happens based on information available at any point in time.
Agile methodologies favour face-to-face communication and use user stories to collect customer requirements and to respond faster to constantly changing requirements. Use of user stories eliminates a need of extensive upfront requirements gathering and writing comprehensive documentation, allowing to us spread the decision making across the duration of the project.
What is a user story?
In short, a user story is a chunk of functionality that is valuable to a user or a customer of the software. In my opinion the most comprehensive definition of a user story was provided by Kent Beck and Martin Fowler in Planning Extreme Programming:
The story is the unit of functionality in an XP project. We demonstrate progress by delivering tested, integrated code that implements a story. A story should be understandable to customers and developers, testable, valuable to the customer, and small enough so that the programmers can build half a dozen in an iteration.
User story examples
A user story is a short written description, told from the perspective of a user, used for planning the system and as a reminder to discuss with your customer the details of the functionality. User stories are traditionally hand-written on paper cards and only represent customer requirements instead of documenting them. A user story has three critical aspects:
- Card: as mentioned before a user story is written on a card. The main section includes title/name of a story and description that reminds everyone what the story is. It may optionally include notes such as reference number, estimated duration and priority. The card is handed to developers when the story is scheduled to be implemented.
- Conversation: all the requirements needed to complete a story are communicated from customer to developers through conversation, usually taking place during iteration planning. Any vital piece of information that helps to concisely explain the functionality can be written on the card as a reminder, but never a full specification.
- Confirmation: this component is the acceptance criteria. It will be used to determine when a story is complete and whether it meets the goal of users. Acceptance tests are communicated by customer at the beginning of an iteration, they help to ensure the software is fit for its intended purpose.
An example of the user story:
As an account owner, I want to check my balance online
How much detail to use
The user stories document the high-level details of a feature; these should provide enough information to allow developers to make low-risk estimates of how long it will take to implement each feature. At a time of iteration planning, developers and customer will discuss in detail all requirements for each story. Additionally, developers can add some annotations on a story card based on the results of the discussion.
The user story must only include functional requirements that are valuable and visible to a user. The following example is not a good story:
The software will be written in PHP
There is no value for the users in this story, because users would not care about the technical aspect. Users are interested in a unit of functionality, an action they can perform, for instance their checking balance online.
The right length
A user story must be short and cover just one unit of functionality, it is just 'a thing to do', without going into details, which will be covered in communication with the customer in later. To understand the expectations of a user we use acceptance tests, written on the back of a story card. These are short and incomplete, they tell us how to test the story. The goal here is to communicate additional details so that developers know the scope of the story.
Writing user stories
The most important aspect of writing user stories is the customer's involvement in the process; only he has the vision how the end product should function. The user story must be written in business language, without using technical jargon, and should state design goals, so that it is understandable to all involved. The customer can then prioritise the stories based on value they add. Moreover, a user story needs to concentrate on the who, what and why of the functionality, never on how. Below you can find a simple template for writing user stories, which you can follow:
Title
One line to help differentiate a story
Narrative
As a [user role] I want to [goal] so that [benefit]
Acceptance criteria
List of tests decided by a customer
Start by writing a title/name of a story. This is used by the team to differentiate the story from other stories. The title should describe an activity and be short enough to fit on 3"x5" sticky note when written with a marker.
The description in a form of As a [user role] I want to [goal] so that [benefit] has many useful features. It implies that all users of the system need to be kept in mind, that developers must take into account what users want to achieve, and that developers need to convert that into a feature that users can benefit from. Additionally, it makes the story writer consider who wants the feature and why. Describing things in this form allows us to communicate the requirement to developers to help them understand it, and it also encourages further collaboration with the customer.
If you struggle to fit the description on a user story card, it is a good indication that narrative may be too long. The story may need splitting into several smaller stories, or it may need to include fewer details.
It is also good to include acceptance tests, which make the story easier to remember and help the team to understand what 'done' means.
Invest
The acronym INVEST stands for six attributes of a good user story, which ideally should be Independent, Negotiable, Valuable, Estimatable, Small and Testable. This next section describes each of these in turn.
Independent
When you write a user story you should take care to avoid introducing dependencies between stories. Each user story should be a self-contained feature that adds incremental value. Any dependencies created at the story-writing phase will lead to complications while prioritising stories and planning the next iteration.
Every so often, we will find that we cannot avoid having stories depend on one another, for instance you have three stories that each implements different type of payment method. You know that work on the first of these stories will take up to four days, with one additional day for the second and third stories. In such a situation, with highly dependent stories, it is not clear which story should be given the four day estimate. The solution to the problem is to revise these stories and combine them into one bigger (but independent) story, eg:
As a user I want to make a payment using methods X, Y and Z
If a story becomes so big that it is not possible to finish it within an iteration, you need to look for other ways of splitting the stories. In our example, we could instead split these stories into two new ones:
As a user I want to make a payment with primary method X
As a user I want to make a payment with additional payment methods Y and Z
If you cannot find a way of combining or splitting dependent stories, a fallback option is to write two estimates on a card; four days for if the story is implemented as the first one, and a one day estimate for if the story is done after.
Negotiable
As I mentioned before, user stories serve as a reminder to have a conversation with your customer about required functionality. The user story card consists of a phrase, in a form of title or description, that aims to remind you to hold the conversation, and has notes clarifying what aspects need to be resolved during conversation. In the process of communication, user story details can be changed or new requirements added. It is important to note that user stories are not contracts, changing them should be flexible up until they become part of an iteration.
Valuable
The feature described by a user story must add business value, meaning that the functionality should be significant to the end user or customer. It is worth mentioning here that not all user stories need to be beneficial to end user of the system. There are many situations where the technical aspects are vital for the customer, for instance the system is distributed across multiple locations and the system purchaser needs to have central point of configuration. In this instance, your story would look something like this:
As an administrator I want to have centralised configuration so I can remotely change settings across all units
The end users do not care where and how system is configured as long as they can use the system without disruptions. However, having a centralized configuration panel saves your customer a lot of valuable time.
How can you guarantee that all user stories are valuable to end user or customer? The solution is to make sure that the customer writes the stories, he is the domain expert and in the best position to specify the required functionality of the end product.
Estimatable
The user stories are written by the customer, but it is the developers' task to estimate the size or amount of time it takes to implement a story based on its complexity. Developers must always be in a position to estimate the story, based on the story’s narrative and any additional notes found on the story card. However, sometimes the development team is not able to estimate a story, usually as a result of one of these three situations:
- Development team lacks domain expertise. If this happens, developers must talk to the customer who wrote the story and discuss the functionality in more detail to obtain overall understanding of what is necessary. Not all details need to be understood by developers at the time of estimating, but they need to know enough to enable the team to estimate the story.
- Development team lacks technical knowledge. The customer may require the developers to use an unfamiliar technology. It is nearly impossible to make accurate estimates in these cases. Agile Programming provides us with a strategy for this called spike. A spike is a short experiment, with a defined maximum time frame, performed by developers with the goal to learn just enough so they can provide an estimate for the story. When using spike, you create an additional story for the spike itself and the estimate is the maximum time frame allowed for the experiment.
- Story is too big. The team may not be able to estimate the story when it is too big. The only solution is to split the story in to smaller, more manageable chunks of functionality and estimate each new story independently.
Small
User stories should be appropriately sized for the project environment. If stories are too small or too big, it makes estimating, prioritising and iteration planning with any certainty very difficult. To determine the 'right' size of story, you must consider the development team, its experience and capabilities, and the technologies in use. To adjust stories to right size you can split epic stories into smaller chunks of functionality or combine small stories into a bigger one.
Testable
Developers must know when work on a user story can be considered 'done'. The only indicators of 'done' are clearly defined acceptance criteria. All tests should be written up front, before work on the story begins. As I already mentioned, acceptance tests should be written by your customer. When the customer struggles to clearly define how a feature should be tested, it may indicate an issue. The story may be overly complex or unclear, it may not have enough value, or simply the customer may require some help in defining tests.
How to collect user stories
Gathering requirements in a form of user stories is an iterative process. On the first pass you gather the main requirements, to give you the feel of overall system functionality. The first user stories are usually the most valuable to the customer, moreover, they do not need to be clearly define at this point. Some stories can work as a placeholder to remind everyone to have a conversation in the future, for instance you can write following story:
As a user I want to search for products
simply because that is all you know at the time. Later the story can evolve and be redefined as a collection of smaller, more concrete stories. Every next iteration will bring smaller and smaller stories, some of them grow or decrease in importance after each iteration. Additionally you can find that lots of stories are missed in first few iterations.
The goal of an iterative approach to writing stories is to get very quickly requirements for a large chunk of a system and have an overall feel how big the application will be, in advance of starting to work on it.
Agile Development provides a set of techniques for collecting user stories that support evolving nature of them. These are:
- User Interviews: this is usually the default approach to gathering stories. The most important aspect of these interviews is to have a good selection of users, preferably performing different roles when using an application.
- Questionnaires: these are a very effective tool to gather additional details about stories you already have or how to prioritise them. Questionnaires also allow you to easily collect information from large number of users. This approach is inappropriate for gathering initial user stories, because they are one way communication channel and do not lend themselves to follow up conversation.
- Observation: Agile development guarantees that software is release as early as possible; you can use that fact and observe your user when they use the application. This gives you instant feedback how the experience can be improved.
- Story Writing Workshop: this is a meeting involving all players with an interest in the project; the product customer, developers and end users. During the workshop the team should only focus on brainstorming ideas and writing the stories, the customer will be able to prioritise all of them at later stage. In the story writing workshop, the goal is quantity of collected stories over the quality. Do not spend much time discussing a story, but make use of the fact that you have entire team in one room and cover as many aspects as you can. Note all stories on paper cards, even when you will later store them electronically, as it speeds up the process. Moreover, some stories may get abandoned as a result of discussion. This technique is a very effective way to rapidly gather initial collection of user stories.
User stories vs. use cases
The basic difference between user story and use case is in the perspective and the intent, which affects the level of captured details.
Use cases focus on the interactions between a system and one or more actors, where an actor can be a user or another system. Use cases describe a process and its steps in sufficient detail they can be understood on their own. The description of interactions is usually in a call-and-response format.
On the other hand, the user story concentrates on the users' values and is much lighter than a use case. It provides just enough detail so that a reader can understand the overall functionality that this user story should accomplish. A use of everyday language is encouraged to make sure user story is understandable by both developers and customers. In contrast to the use case, a user story is a reminder to have a conversation with your customer.
Summary
So why would you go to the trouble of dropping your current processes and instead use user stories to collect system requirements? Well, user stories emphasise collaboration with your customer, they encourage a verbal communication rather than tons of documentation. The ensure that the developers and the customer will interpret a statement in the same way. Since all user stories should be 'estimatable', it makes it very easy to use them in project planning; they are also small enough that you can fit few of them in one iteration. Finally, user stories are collected in iterative process, giving you the flexibility to add, change and drop requirements as your project progresses.
