Type for search...
codete comeet how to write good user stories main 4882c02be5
Codete Blog

How to Write Good User Stories

Zrzut ekranu 2023 05 19 o 16 41 55 b8e4a7a3f5

19/05/2023 |

12 min read

Marcin Kuśmierz

Today, I will talk about how to write user stories. Crafting them requires a balance of technical knowledge, empathy for the end users, and the ability to set priorities. But I must warn you: there is no one-size-fits-all formula for that. 

Instead, I will show you some tips on what makes a good user story. And when you use them properly, you will be better equipped to collaborate with your development team, maintain clear communication with the business, and create well-thought-out user experiences.

But before that, let’s ask ourselves how we should understand the user story.

Table of Contents:

  1. What is a user story?
  2. What makes a user story good?
  3. Sections for the rescue: a proven draft for good user stories 
  4. Writing User Stories: Conclusion

What is a user story?

As a product manager, one of my crucial responsibilities is to bridge the gap between the development team and the end user's perspective, ensuring that their needs are met, and their experiences are exceptional. 

I create user stories for that very purpose — usually several separate ones for the project simultaneously. They serve as building blocks for effective software (or product) development, defining the product’s functionalities from the user’s perspective, providing a comprehensive description of their requirements, and a roadmap for the development process.

The Agile Alliance defines user stories as "short, simple descriptions of a feature told from the perspective of the person who desires the new capability." This definition puts emphasis on humanizing the persona by setting them in a specific product/service use scenario. Hence, the user story format showcases their perspective, focusing on their needs, goals, and desired outcomes. We can give context to what they might look for and what improvements they need to complete their goal. 

User stories are primarily used in agile software development methodologies, such as Scrum or Kanban, where iterative and incremental development practices are followed. This way, development teams can align their workload with the user’s expectations, prioritizing the tickets in relation to the collected stories. 

And because user stories are written in a simple, non-technical language, they can be freely used as "a reminder to have a conversation" (Ron Jeffries) with multiple teams across the project, including stakeholders like the development team, product owner, management, and business. 

They typically follow a specific format, such as: “As a [persona], I [want to] [so that].” Being more general, this could also be explained as: "As a [type of user], I want [an action or feature] so that [a benefit or value]."

Keep your sources verified

You may now ask yourself, “How do I collect the data to predict the user’s behavior or set the right functionality design path?" 

In most cases, user stories originate from how business departments want the product to work (from a user perspective). Although they may have some access to real users' data, they probably wouldn’t share it with you due to the strict data privacy policies. Instead, they may deliver pre-set requirements to your team to build the story around, including a summary of how users are already behaving in the product’s app or website or some improvement ideas. 

But there’s a catch. The initial requirements should be verified as you’re usually presented with the data interpretation instead of its objective source. 

To do this, you can use the five-whys method, which allows you to dig deeper into the problem’s core. This can also fix the common issue of omitting the "so what" added value component, giving the experience a deeper meaning. 

Sometimes all this results in redesigning the whole experience, as your team may discover that the solution asked for is not the solution to the product’s functionality problem. 

What makes a user story good? Learn to write agile user stories

You probably recall a situation where to start working on the project, you were faced with volumes of documentation or an empty requirement list. So firstly, you had to go back and read into documentation or attend multiple calls to determine what was to be done and how. Both positions are hopeless, as you were unable to start implementation quickly. 

User stories take all those problems away. 

But to function correctly, there are four conditions to meet:

  • Simple language. Avoid complex vocabulary, as this may be received as discriminating towards non-English speakers and lead to more confusion, as people will interpret your vague descriptions in their own way.
  • What we need. Define the goal of this story clearly. Use step-by-step lists to visualize your user’s path to this goal, including every action - paired with the expected result, to make the journey easy to understand.
  • What we don’t need. Make sure that you’ve written down what is not part of the scope. This is crucial as the specific user story handles only a part of the design.
  • Remember about the DoD. Teams have a Definition of Done, and our story acceptance criteria need to be written in a way where we have clear points related to the DoD.

User stories provide a framework for meaningful discussions, exchanging ideas, clarifying requirements, and identifying potential challenges. Product managers can use them to capture product functionality, streamline the development process, reduce rework, and deliver software products that address the core needs of their users. 

And to make the most of it, I created a user story template composed of several sections that portion the knowledge needed to start the development into highly-organized, easy-to-understand information essential to implementing the required functionality. 

Sections for the rescue: a proven draft for good user stories 

Let’s pair the theory with a practical scenario to maximize this part’s understanding. In our fictional team, we were tasked with the following task:  As a User, I want to be able to place an order so I can receive the ordered products. 

Pretty straightforward, right? 

Section no. 1: Pre-conditions

The scenario could vary in multiple directions, so it’s best to write them all down. To do that, we need to set the pre-conditions, specifying the starting point. This section should include all known criteria to be met to start the journey. 

Following my example, we can already recognize that: 1) The user must be in the shopping cart view, and 2) There must be at least one product in the cart. The user position is quite obvious, as we cannot finalize the order outside the cart view. And when the cart is empty, we’re redirected to a different subpage [“cart is empty”], which prevents the user from proceeding. So, to start the journey, both preconditions need to be met.

Section no.2: Post-conditions

Now we can move on to the actual goal of this specific user story. As the User is already on the “summary” page in the cart and has at least one product in it - our goal is to be able to change the quantity of the product. It seems simple, but it's best to write those acceptance criteria down to ensure every team member is on the same page. 

Section no. 3: Requirements 

This is the place to write down all details related to the user story that could influence achieving its goal. You can interpret it as a list of additional requirements that must be addressed to make functionality available.

For example, we could specify here that our item quantity is not unlimited - and define the input as between 0 and 9. Or that it will adjust its value to the actual in-stock status and won’t allow the user to pick a number higher than that listed as available. Or that we don’t want the user to insert the value manually, defining our input as a selection to choose from.  

At this point, we should also list everything that should not happen in the user story. In this case, we plan to send an e-mail notification after the purchase, so it shouldn’t be triggered after a user is added (too early). Also, Google Maps should not allow for the auto-filling of fields. 


Minimum quantity: 0, max: 9

Input should be a select

If you’re developing an MVP, you can start with one or two smaller user stories, then put in the requirements that, i.e., some pop-ups won't be implemented as it will be done in another ticket, which can be later linked. This way, people will know what is the acceptance criteria and what waits in the product backlog. 

Section no. 4: Normal Flow

When you think about agile user stories, you usually imagine the flow; a step-by-step representation of how users will behave in our functionality. 

Using our example, we’re giving the context of where we are at the start of this journey (“summary” page), what we are doing (placing an order), where we should be redirected (“order placed” page), and what comes next (e-mail notification sent). 

  1. When I click the “Place Order” button
  2. Then I should be redirected to the “Order Placed” page
  3. And I should receive an email notification

But that’s not the end, as we now have to analyze the additional requirements to receive a more comprehensive view of this hypothetical situation. So, we should specify that all items in the cart are in stock when the order is placed. Order status should also be set to “New Order.” The cart page should display all products from the cart, shipping address, and payment information.  

All that seems logical, but it must be specified (and written) to avoid wasting time on additional user research, meetings, or changes. 

After this update, our Normal Flow list looks like this:

  1. When I click on the quantity
  2. Then I should see all available quantities
  3. When I choose one
  4. Then I should see a new quantity of the product
  5. And shopping cart cost should be recalculated

[the e-mail notification has been pushed to another ticket]

Each step should be written down, delivering straightforward solutions so the development team won’t implement something unexpected. In the example above, cart recalculation can be done automatically or manually - by placing the “recalculate the cart” button on the shopping cart view. But if you choose to do so, another step should be included in the user story’s flow [hence, the acceptance criteria change] to make sure that there is no possibility of placing the order without recalculating. 

Generally speaking, as the number of alternative flows may vary, the normal flow should suggest only one path. 

As you’ve probably noticed, the language in my user story examples is easy to understand. This is planned, as one of the most important rules in creating user stories is their ability to be wildly understood. To achieve that, I’ve got inspiration from Gherkin, which uses “WHEN,” “THEN,” and “AND” to simplify the processes in a step-by-step method. 

Section no.5: Alternative Flow

The next section is Alternative Flow, which focuses on all actions in our user story that expand the question: what should happen if the person does something differently? I’d like to specify that in this context, ‘different’ should still be related to the exact situation we’ve put our user in. 

This scenario version should explore the consequences of misclicks, wrong field input, or even using screen readers, keyboard navigation, or other accessibility-oriented technologies. In other words, the alternative flow covers all the interactions available within the user story - not following the suggested, normal flow but still possible. 

In relation to our example, we can predict the following scenario:

  1. When I click on the quantity
  2. Then I should see all available quantities
  3. When I click outside of the select
  4. Then select should be closed
  5. And nothing should be changed

If you have multiple alternative flows, it’s good to differentiate them by name.

Section no. 6: Data Inputs

The next section is Data Inputs, which is extremely useful when we have more specific information to share with our team. Using the table, we can easily squeeze all the details into one place to explain the workload.  

My typical table composes of the following columns: Field Name, Type, Mandatory, Editable,  Source of data, Validation, and Comments. Remember to use easy language and precise information when filling out the data. If you have multiple forms, it's best to name them differently. 

Section no. 7: Messages

This is a separate table used to collect all the necessary messages for pop-ups, form fields, and other short pieces of text needed for the story to guide the user through properly. You can use columns like Name, Type, and Text here. This is also a place to paste all the translations so the team knows which text is designed to go where. 

Section no. 8: Design

No matter how small a piece of the design your user story is based on, always include the shareable links to the design so every team member can quickly check whether their work is in sync with it. 

Writing User Stories: Conclusion

As I guided you through my methodology of tackling the user story to make it as useful to the team as possible, I need to add one more thing about the structure: it's fully adjustable. 

The current version results from numerous cooperations with clients from many backgrounds - I generally use it as a blueprint to collect the requirements quickly so that most roadblocks are avoided at the early stages of development. But, if you need a few sections more (or less), feel free to adjust my user story template to match your specific situation. 

When writing good user stories, you should always focus on what the story points are. Collect all the data you can, but only about a specific scenario within the project’s scope. Don't overcomplicate things; too much information will force people to study lengthy descriptions instead of solving the actual problems. Put yourself in the user's shoes and think of all the “what ifs” they may try to do when placed in the functionality your client is trying to implement. Also, set the acceptance criteria to complement DoD.

And remember, fixing (and clarifying) things on paper - even virtual - takes minutes, while fixing the already deployed solutions takes weeks (and thousands of dollars). 

If you need more guidance on the topic, drop me a comment under this article. 

And if you’d like to book a session to discuss the potential of improving user stories within your product or service, I encourage you to reach out through this form. 

Rated: 5.0 / 2 opinions
Zrzut ekranu 2023 05 19 o 16 41 55 b8e4a7a3f5

Marcin Kuśmierz

Project manager at Codete with more than six years of experience. I am a fan of products that make a difference in our lives—photography, computers, and board games.

Our mission is to accelerate your growth through technology

Contact us

Codete Global
Spółka z ograniczoną odpowiedzialnością

Na Zjeździe 11
30-527 Kraków

NIP (VAT-ID): PL6762460401
REGON: 122745429
KRS: 0000983688

  • Kraków

    Na Zjeździe 11
    30-527 Kraków

  • Lublin

    Wojciechowska 7E
    20-704 Lublin

  • Berlin

    Wattstraße 11
    13355 Berlin