5 tips for Writing Better User Stories

Share this post:

User stories are one of the main tools that come with Agile software development. No matter whether you are doing Scrum, Kanban or both, user stories are a must have. What I find interesting is how often this powerful tool is being neglected by both product and technology people. And the consequences could be really disappointing.

During my career as a Product Owner, I’ve worked with people from many different geographies and religions, both collocated and distributed. What I’ve learned the hard way is that gathering business requirements and then transforming them into something meaningful for a development team can be challenging.

Below I’ve listed 5 key tips to follow while writing user stories. My assumption is that you are familiar with the concept of what a user story is, so I won’t be describing that in detail.

1. Make sure your title is clear and properly describes the business requirement

Let me ask you something. How often do you receive emails at work with subjects that mean little or nothing to you, but you are supposed to read them anyway? I guess this is not that a rare.

Now imagine that you are a software engineer and you need to prepare for your team’s upcoming backlog refinement session. You open the backlog and you see a user story that simply says “Registration”. Hmm, what would that mean? Registration where and who is going to do it? Is it a user facing app or a back-end tool? It’s obvious that this title is unclear and it doesn’t give the reader a good idea what to expect. If the title is not easy to understand, the chances are that either the user story is too big or it’s too vague and not ready to be worked on.

How about “Create a user account on the website”? Now that gives you a better understanding on the topic and you know that the story is about a user account registration on your company’s website.

You are now prepared to open the user story and deep dive.

2. Describe the user story from the perspective of the person who will benefit directly from it

You have the user story in front of you and you expect to learn more about it. What you see is “As the system, I would like to register users on my website”. What you could understand from this is that the system is supposed to have strong artificial intelligence so that it knows that the more users you have, the better. In reality, this simply shows that the author doesn’t know who the main actor/stakeholder is. That’s too bad as it’s highly unlikely that the acceptance criteria to follow will be adequate.

There is also an option that you won’t even see an attempt by the author to summarize the user story and share who the actor is. Not knowing who you are doing a user story for often means that the user story itself might not make much sense.

The summary of a user story should follow a very basic principle that describes the main actor, what he would like to do and why he would like to do it. The template is “As an actor, I would like to do something in order to achieve something else”. For example, “As a user, I would like to register on the company’s website so that I can start using its features”.

3. Provide a background for the business requirement

It’s always good to provide background to your user stories although it’s not mandatory. I use a section that I call “Overview”. This doesn’t and shouldn’t be long, a few sentences at most. It could provide useful information as to what the current state of the system is before this user story is implemented.

If we use the example from the previous two tips, an “Overview” section could have a text like the following:

“As part of building the foundations of our application, we need to provide a functionality to our users to register on our website. As of now, this is only possible if the account is manually created in the database.”

It’s important to note that business requirements should not be included in the “Overview” section. They belong to the acceptance criteria.

4. Define the acceptance criteria

A common approach to acceptance criteria and user stories in general is to provide several sentences in a waterfall style that basically describe everything at once. The main challenge here is that the business requirements are often vague and it’s difficult to get what’s the minimum set of features needed so that the user story can be accepted by the Product Owner once developed.

There are two types of acceptance criteria that I use on a daily basis:

  • Given/When/Then

This is the most common and descriptive approach. As seen in its name, it provides three main clauses that describe an acceptance test/scenario.

GIVEN some context

WHEN some action is carried out

THEN a particular set of observable consequences should obtain.

For example:

GIVEN a user visits our company’s website

WHEN he decides to register and create an account

THEN the registration should be successful.

This template is very useful to both the Product Owner and the development team as it provides detailed information about the scenario in question using common language and at the same time creates the foundations of a test plan.

  • Decision tables

Decision tables are used in case the user story involves multiple scenarios with repeatable context but different outcomes due to changing conditions. They are very common when testing validations.

The below table provides a simple example as to how decision tables could be used as acceptance criteria. Please follow this link if the table is not shown on your mobile device.

5. Add a section for “Technical Details”

User stories are meant to describe business requirements. They should be written in a common language so that non-technical people could also understand them. Although I agree with this, I’m a firm supporter of having the whole information about a particular feature in the same place. That also includes technical details that will mainly benefit development people. I use the term “Technical Details” and I place it at the bottom of the story so that it’s only read if required by the reader.

To summarize, user stories are a crucial tool of the toolbox of every product owner. They increase the probability of successful delivery. Not using them to their full potential could cause problems when the feature is presented to its stakeholders and doesn’t meet their needs. Don’t spoil your chances to succeed by letting your user stories be vague and incomplete. It’s easy to change this. Start today!

Share this post:

Leave a Reply

Your email address will not be published. Required fields are marked *