Write High-Quality User Stories (How to)
Author: Bas de Groot
It’s refinement time. Everyone at the table looks confused, some also grumpy. Forty-five minutes have passed since we started discussing a user story that only has a title without further description. Our discussion cleared up some things, but details remain fuzzy. Afterward, we all agree our meeting was a waste of time.
Most software engineers are part of similar refinement meetings at least once in their careers. Inferior quality or incomplete user stories are the root cause of these dreadful meetings.
This article describes how to create high-quality user stories, and why this is an important skill to master.
What makes a high-quality user story?
A high-quality user story always meets the following requirements:
As you can see, writing a high-quality user story is no rocket science. By themselves these requirements are simple, the power lies in their combination. All team members can understand a story that meets these requirements, which allows for efficient discussion during refinement.
Research
Research sometimes feels like a waste of time. It may seem more efficient to just start writing code and figure things out as you go along. The opposite is true. In my experience, time spent researching upfront always saves you time later on.
Always verify
Mr. Eugene Lewis Fordsworthe once said: “Assumptions are the mother of all mistakes”. Although he later rectified this statement, I still think making assumptions during software development is dangerous.
Imagine another team provides an endpoint that you want to use. It seems like a simple decision to use this endpoint because it matches your needs. You implement your feature and everything works well. A few weeks later you receive a deprecation notice for the said endpoint, which means a big part of the code you wrote a few weeks ago needs to be refactored.
Instead, drop the owners a quick message to verify this endpoint is what you need. Explain that you intend to use their endpoint and ask if your team needs to know anything before starting with the implementation. The other team will tell you they will deprecate the endpoint soon, but a new version is coming in a couple of weeks. This information would have saved you a lot of time.
Focus on what matters
Focus your research on things that are hard to change once the feature is implemented. This is where the biggest risks are.
All things your application exposes to the outside world are hard to change. Response model changes of your public API might even lead to work for other teams. Database model changes can be quite tedious as well. By doing research you have a higher chance of getting it right the first time.
Improve estimations
Some stories are hard to estimate. You can improve estimation accuracy by documenting your research findings.
Let’s say you have a story to upgrade a library to a new version. By reading the update guide, you discover that only two apply to your team’s application from the nine steps in the guide. This is important information to document, as it helps your team members to make more accurate estimations during refinement.
Useful resources
Your research will sometimes yield useful resources like links to documentation or architectural images. Add these resources to the user story so they can serve as references later.
Provide context
High-quality user stories always provide context. Some user stories need more context than others. Small bugs can do with less context than complex features.
Start with why
You should explain why your team needs to implement a user story as this has two benefits. First, understanding why something needs to be done increases motivation. Second, explaining why forces you to explain the problem at hand, allowing the development team to come up with better solutions during refinement.
If it proves difficult to describe the why part in a couple of sentences, it might be a good idea to split up the user story into multiple smaller stories.
The big picture
The hardest part of software engineering is building future-proof solutions. By describing the big picture, you are more likely to find a future-proof solution.
The big picture description should answer questions like: How does this feature fit in the current landscape? Will we be expanding upon this feature in the future? Is this feature part of some bigger plan?
Make it easy to read
People get distracted if your user story looks complicated and painful to read. The chances of an excellent refinement discussion are slim if your colleague only makes it halfway through the text.
It might seem obvious, but the best way to improve readability is by using paragraphs and punctuation marks. Besides the obvious, taking some simple rules into account can improve the readability of your user story a lot.
Separate different sections
With styling, you can separate different sections of your user story. One way to do this is by using headings. Separations between sections make your user story less daunting to read. Separate sections also allow the reader to skip back and forth between relevant sections and to refer to specific sections during a discussion.
Don’t go overboard on styling, less is more. Using a different color or font for each section is a bad idea as it will only distract your readers. Instead, aim for consistent styling across all your team’s user stories. Like most online scrum tools provide, story templates can be a great help to keep your styling consistent.
Code blocks and variable names
Technical user stories often contain code examples. Without formatting, the code is hard to read. You can improve the readability of code snippets by placing them in code blocks or GitHub gists. If possible, enable syntax highlighting. Doing so will make your code examples even easier to read.
A similar concept applies to variable names, method names, and class names. Without formatting, they are hard to distinguish from normal text. An elegant option is to format these names like this.
Terminology
With terminology, consistency is key. It’s clear to you that a product overview page and a product list page are the same things, but mixing up both terms might confuse your readers.
At least make sure your terminology is consistent within a single story. Better yet, use consistent terminology across all your team’s user stories.
Closing thoughts
By following some simple guidelines it is possible to create high-quality user stories. As we’ve seen throughout this article, high-quality user stories come with a lot of advantages.
By doing research beforehand there is a higher chance of finding a long-term solution and a lower risk of wasting time. Anyone can understand user stories that provide context, which makes for efficient discussion during refinement. By making them easy to read, you allow your team to concentrate on the contents instead of being distracted by an enormous wall of text.
We haven’t discussed the ultimate advantage of high-quality user stories. High-quality user stories promote knowledge sharing. This is because everyone on the team can understand these stories, which makes them a valuable source of information for junior developers on your team. They are also of great value to more experienced developers as it allows them to keep an overview of the big picture.
Thanks for reading. I hope this was helpful. If you have questions or feedback, feel free to leave a response.