7 Best Practices for Writing User Stories
Building software is hard
Many people say that building software should be like building houses and wonder why so much effort is needed to build working products. Fundamentally, building software is different from construction as we’re hardly ever building a repeatable product.
As such we need to use different techniques to help us navigate the uncertainty that software development entails. User stories are one technique that can help.
User stories are a very simple and effective way to document the features that you need to build in your software. They help developers and product managers focus on what’s most important, and they can also be used as part of an Agile development process. But while user stories are useful, they can also be very difficult to write well.
As with any technique, there are best practices that can help you to get the most out of them, and in this article, we’ll discuss seven best practices for writing user stories — from how to get started talking with your client about their needs (and not yours) all the way through creating acceptance criteria for each story once it has been completed by developers.
Talk to Your Stakeholders
The most important part of a user story is the person who will be using the software. You should talk to your client about their needs and goals for the project, including:
- What do they want you to build?
- Why do they want it?
- When will they use it?
To answer these questions, you’ll need to spend time with your stakeholders, build relationships, watch them working, understand their business needs and turn those needs into features that can help them.
Keep Your User Stories Simple
You should keep your user stories simple. This is for several reasons:
- Simple stories are easier to read. If you add too much detail, it can be hard for someone new on the team to understand what needs to be done.
- Simple stories are easier to understand and explain from one person’s perspective (e.g., a developer). Each element of your story should be important. User stories are no place for “filler” — if your text is not adding value, don’t write it!
- Simple stories are easier to test — you should be able to test each item in a story as soon as possible after writing it — and this means that you shouldn’t have any unnecessary fluff or complexity in there either.
It’s Not About the Format; It’s About the Content
The format of a user story is not important. It’s just a way to communicate what you are trying to achieve with the feature. There are many ways to document features, but it is important that your team agrees on one consistent format for documenting them. Some teams use very formal documents, other teams might use something much less structured like sticky notes on walls.
Whatever works best for your team and project environment is the right way for you. Personally, I like to have a format for each story based on the user story text, any background notes that may be helpful, and then any acceptance criteria.
Keep Your User Stories Small
User stories are a great way to manage your work, but if you attempt to work on stories that cover too much functionality, you can risk biting off more than the development team can reasonably chew.
Stories that are too big tend to carry more risk with them than smaller well-defined stories. If the functionality has too many aspects to it, too many unknowns, or perhaps changes too much of the code base at once, there is a risk that the development will encounter difficulties and get bogged down. It is generally good practice to keep your user stories as small as possible and cover a discrete piece of functionality to minimise this risk.
Let’s start with an example of a user story that’s too long: “As a new bank customer, I want to be able to apply for credit cards and loans without having to fill out any paperwork.” That’s not going to cut it.
The example contains multiple scenarios, in this case, applying for different types of accounts, but those should be broken down into separate user stories. The second problem is that it’s too general and doesn’t really describe what needs to be done in detail.
This example should be seen as an “Epic” or an overarching story that can be broken down into subfeatures and user stories and delivered in a series of steps.
Don’t Be Afraid To Split Your User Stories
Breaking down a user story into smaller stories is not only acceptable, it’s encouraged. If you’re working with a team of developers, this will help them achieve the desired outcomes in shorter amounts of time.
If you still aren’t sure whether your user story should be broken down into smaller ones, ask yourself these questions:
- Does it feel too big?
- Does it contain multiple aspects that could be delivered separately?
- Do the acceptance criteria reveal ways to break down the story?
- Is it the kind of story that will take a long time to deliver?
Each of these might be a sign that you need to split the story into smaller chunks.
Create Acceptance Criteria
Acceptance criteria are the conditions that must be met before a user story can be considered complete. The process of writing them is very similar to writing use cases, but there are some key differences:
- Acceptance criteria are more specific and concrete than use cases. While both documents have acceptance criteria, user stories typically include fewer steps than use cases do.
- Acceptance criteria should focus on functional and performance requirements rather than business requirements; that is, they’ll outline how your app will function from the user’s perspective instead of focusing on what needs to happen behind the scenes.
- The acceptance criteria are a series of tests that will ensure that the software is doing what the user needs; asking any professional testers you have on your team to help write them is a great way of gathering a different perspective that will really check the code.
Acceptance criteria can be written as a list of steps or you could experiment with a table in which each column represents an important scenario (e.g., what happens when someone first opens your app) and each row represents an outcome (e.g., “The user sees a dashboard with their name”). This latter approach may lead you to explore “Given, when, then” format of Test-Driven Development (but I’ll leave that as a subject for another day!)
Either way, the acceptance criteria allow you to test how well each feature works after it’s built.
Consider Using a “Definition of Ready”
A “definition of ready” is a useful way of checking that your user stories are ready for the development team to pick up and work on. It’s similar to a “definition of done” which is a checklist used to check whether functionality delivered by a team meets certain minimum standards (i.e., tests pass, documentation updated, code deployed, etc).
As business analysts or product owners, we are used to dealing with uncertainty. Sometimes, we just don’t know the answers to many of the questions that need to be resolved before starting development.
For example, let’s assume we have a time limit on a process but the stakeholders haven’t agreed on what the time limit is yet. Or perhaps we are waiting for a legislation to become law. In these cases, we either work around the uncertainty or have to acknowledge that requirements in these areas may have to wait.
A definition of ready can help you to understand what additional work is needed or what conditions need to be met before starting development.
A rudimentary definition of ready might include factors such as:
- A status — do you think the story is ready yet or are there too many uncertainties?
- Has it been written?
- Is it in line with your stakeholders’ expectations?
- Refinement — has the user story been reviewed with the development team and were they happy the story could enter development?
- Are the team comfortable that the functionality can be delivered in a timely manner (i.e., comfortably within a sprint, or reasonable timescale if not using Scrum)?
- Are any critical acceptance criteria written down?
- Can the user story be split into any smaller parts?
A good definition of ready will give you a checklist to work through to help you be certain that you’ve completed your work before the team begins development.
As a business analyst or product owner, it’s likely that you’ll spend a fair amount of your time brokering agreements and writing those agreements down. User stories are a good way to capture your stakeholder’s needs and to communicate with programmers and end users about the features that will make up the product.
Hopefully, these best practices should help you to write better user stories, or maybe just give you some areas for further research. It’s worth the effort as well-written user stories can help agile development teams in uncertain environments develop in small incremental steps, allowing options to be tried and reactions tested to changing situations.
Building software isn’t easy, so any techniques that help you navigate uncertainty and change will form a valuable part of your armoury.
And remember, it’s not about the format; it’s about the content.
If you found this article useful, you might be interested the book it came from, or the course that takes you through the content in a more interactive manner. In the book and course I explore user stories in more depth, work through specific examples and include loads of lessons I’ve learnt over the last 20+ years. You can find the materials here.
