How to write better user stories? — A template

Rebekka Orth
5 min readAug 18, 2022

Introduction

By now almost all software development teams use either Kanban or Scrum or some sort of their own version of the two. What your team uses does not really matter as long as the processes work for all team members and you are able to track your progress and productivity over time. Both approaches of managing your day to day work as a team involves writing tickets. For this, most teams use so called user stories.

User stories represent the smallest possible piece of work that provides value to the end user. They have a fixed scope and are implementable during a specified time period. E.g. during one sprint. Their purpose is to put the end-user into the focus of the conversation and to enable engineers/ designers to better understand what / why / for whom they are building features etc.

In general you and your team can decide what to include in your user stories, but over time I have found a format that seems to work for different types of development teams.

What does a good user story need?

Bill Wake introduced the so called INVEST-principle for writing user stories that defines what a good user story should contain.

The format of your user stories does not really matter as long as the content of your stories follows these principles. Nonetheless, since writing user stories and adding them to the backlog is a continuous task it is best to define a specific format. This format should be created within the team so that everyone is aligned on how your stories look like.

A template for a good user story

During my time as a developer and now as a consultant I found the following template came in quite handy. I have introduced this template in multiple teams and it got adopted quite quickly by other teams as well. In order to write consistently good user stories, I find it best to create a very low threshold for actually writing well-structured stories. Most tools, teams use, like JIRA etc. give you the possibility to create a template for different types of tickets. Use it.

In a first step, I recommend to create a user story structure with your team. Afterwards you should add this structure as a template to whatever software you’re using to manage your tasks.

The following template is the one I have introduced. That being said, you should adapt it to your team’s needs. It is quite detailed on purpose and not every user story requires that amount of detail. Nonetheless, I find it important to have a detailed template and to just remove certain parts that are not needed on a case by case basis. To make it as uncomplicated as possible, it is best to just add it as headlines in the description box of the ticket-template.

Template

  • What?
  • Why? (provide as much context as possible)
  • How? (added by engineers during refinement)
  • Acceptance Criteria (<= 8)
  • Test Cases (given — when — then)
  • Example(s)
  • Additional Info (documentation / etc.)
  • Required Assets (designs / images / etc.)
  • (External/ Internal) Dependencies

Who should write user stories?

The responsibility for continuously writing tickets have one or multiple members of the team who represent the business side of the product / part of the product. This usually means that the product owner / product manager / business analyst / etc. is writing the tickets. Nonetheless, it is crucial in order to take full advantage of user stories to include engineers into the writing process.

How to work better with your user stories?

The best user story template and the best intentions do not mean much when they are not used right. Most of the time the person writing the ticket (e.g. PO/ PM/ BA/ etc.) can fill out most of the template on their own. Nonetheless, often enough they lack the in-depth technical knowledge to write a story that is estimate-able straight away. And that is totally okay.

In my experience most teams have sprint plannings, estimations, sprint reviews and retros set as their regular team meetings. But many don’t have a regular refinement meeting. They tend to start refining during the estimation meeting or struggle with developers starting tickets that block them quite quickly when certain information are missing or are misunderstood. In my opinion, a regular refinement meeting is crucial for a productive development process and provides a nice gateway to have a continuous, open discussion about upcoming features and tasks. Moreover, in my experience it is best to have this refinement meeting once a week. Of course, as always, it is upon you and your team to decide the frequency. Though, having it weekly keeps everyone in the loop and holds the one writing most of tickets accountable for actually writing tickets.

So, what should happen in this meeting? The meeting is all about the person who wrote the ticket introducing it to the development team. Here, it is not necessary for all developers to be there but at least 2–3 developers should attend. When the ticket has been introduced, the engineers can ask questions and start the discussion about what needs to be done to implement it. During that time the how section is completed as well as other open points in the template that are important for the implementation. The main goal should be to make the ticket estimation ready.

In my opinion, it is important to separate the refinement and the estimation of tickets since combining both in one meeting usually leads to a very energy consuming meeting where most people zone out at one point and only two people keep discussing things. This then usually leads to confusion and misunderstandings when a ticket is started at one point. Having a clear focus during both meetings keeps everyone engaged and means that tickets are discussed multiple times before the implementation. This is also crucial because for one the whole team is involved and has to work together and secondly, as we all know, sometimes we have to talk about things multiple times to get to asking the right questions / see problems etc.

Where to go from here? — Other resources on the topic

--

--