How To Write Great User Stories

Photo by Startup Stock Photos from Pexels

Writing user stories is an important aspect of the Agile process. It’s important because the way a story is written can affect all the other aspects of how that story goes through the software development lifecycle. Poorly written stories don’t just create confusion during estimation or implementation, but they become costly and time-consuming. And long to finish stories that bloat software development cost don’t necessarily lead to good perception of your team, good team dynamics, and many other problems…

So how does one write a good user story?

Its starts with an appropriate title. If a software developer can’t understand the root of the user story from the title, or the title goes against the rest of the description, all you are doing is creating confusion and ambiguity. Both of which wastes developer time and resources (not to mention the time of the writer of the story).

One of the best strategies I’ve found is to actually give the story a title last. Fill in the description, using all of the tips below, and then pull out the most crucial part of the Single Sentence Summary (see below) to use as the title. When these two pieces of information are in-line with each other, it’s hard to add confusion or ambiguity in between.

Every time I pick up a story from the backlog, I find myself wanting to understand the who, what, and why as soon as possible. I want to know what the story is aiming to accomplish, why the story is needed, and whom the story is intended for. If I can understand those three things, I usually have enough context start planning and implementing a solution.

A great story should, therefore, convey all three of these details. You can’t just write down a short description in a jiffy saying “Do this thing” and move on. I’ve been guilty of that before and it came back to haunt me when I couldn’t explain why the story existed during a grooming session. Its a pretty embarrassing moment when you can’t explain your own story 🙁

For instance, if you find a bug, what is the actual problem? Why is is important and what is it breaking? Who does this bug affect the most? If you find a technical debt issue, what would improve if the story was implemented? Why is it technical debt? Does it really just affect developers or users too?

Taking the time to answer these questions can be vital to writing a great user story. But how do you express this information? I usually look to a Single Sentence Summary to start.

Speaking of which…

A single sentence summary about what a story should accomplish is the single most important part of a story. Why? Well, if you can’t express why a story exists in a single sentence, it might be that the story is too big or isn’t clear enough. And make no mistake, clarity is king when it comes to user stories.

I try to use a simple form to help flush out this sentence. The form is below:

As a user of a solution, I want some desired feature or bug fix so that I can reap some benefit.

This form is easy to read, leads the developer of the story to think from the perspective of users within the role specified, and answers all of the what, why and who from earlier. In fact, you could effectively substitute those into the form above to make a simplified version:

Take the time to rewrite this sentence a few times. Make sure the user role isn’t to vague (like “someone using our API”) or that the what is too big (“want a consistent API”). Be as specific as you can, without elaborating too much.

Once you have the who, what and why in a single sentence summary, you should also have an appropriate title that leads to a clear and consistent picture of what a developer needs to implement. But even after that, you will still need to be more specific about the details.

The what that we talked about earlier won’t usually be enough to weed out ambiguity or provide enough details for implementation. A common what might be “Create a new API for retrieving random cat photos”. That is clear and concise and the general direction is given, but things like the API endpoint name or the file formats allowed haven’t been (and shouldn’t be!) expressed in the what. These finer details need to be in a separate Requirements section.

Your Requirements section should be a set of actionable and measurable details that a developer can use as guideposts about their solution. I like to put these in a story in the form of a bulleted list that is usually one short sentence in length. Anything longer should be broken up into multiple lines.

Using the example of “Create a new API for retrieving random cat photos”, a Requirements section might include

• The existing API endpoint of /photos/cats will be augmented with a new query parameter of pickAtRandom which can be true or false
• If pickAtRandom is true, then the API returns a collection of one cat photo selected at random
• If pickAtRandom is false, the API returns a collection of photos as it did before

Stay Away From Implementation Details

These Requirements should try to be specific and detailed, but stay away from too many implementation details if possible. For example, an requirement that states “Should use a new Random() for every invocation” is too much in the weeds. When these sorts of details are included, they actually create problems when a specific implementation detail listed in the story hinders development.

If you don’t think that happens, trust me: it happens all the time. In fact, it happened to my team this week. We had a story to implement a new lookup for data and we were told the data structure to use. After it was implemented, we realized we had a performance problem. After some digging, we realized the data structure we were told to use was in fact the bottle neck; other structures were performing better in our testing. Now, we had to get with the story writer and product owner to change the requirements (one of which was on vacation).

In this case, it would have been better to simply include a set of Performance Requirements, which is totally appropriate for a user story. I won’t go into too many details here (I’ll provide an article specifically for performance requirements in the future), but its a lot like normal Requirements: they need to be specific, actionable, and measurable.

Lets apply these principles to the example I’ve hinted at about writing an API to return random cat photos. Here is a screenshot of a Trello board with this story.

Hopefully you can see how all of the guidelines from this post worked together to write a great user story. Of course, there are many other resources to help you. Checkout 10 Tips on Writing Great User Stories and even just Wikipedia.

What other tips and guidelines do you use for writing great user stories?

Till next time!