Writing user stories: Definitions, best practices, examples & exceptions

Writing user stories is not an easy feat. That is when the expected outcome is a good user story. An ability to view the world from someone else’s perspective is not programmed into our default skillset. People high on the compassion spectrum may find it more innate, but I would proceed with caution as biases always lurk around to distort our judgmental compass.

In this article, I want to focus on an in-depth analysis of writing user stories from different angles. It’s only fair that I admit ignorance before we dive in. There is a lot I still do not know about them. However, my long-lasting journey through the confines of Agile has taught me a lot. We made errors, faced challenges, and we learned lessons. Equipped with the experience, I feel confident enough to shed a bright light on the topic.

What is a user story?

The first baby step is to understand the meaning behind the phrase. A “user story” has an actor who sits central to the action. The second part, the story, describes the action and provides more context to the user’s behaviour. Since Homo sapiens proved to be a rather self-centred species, the final and excluded part of the phrase is the benefit resulting from the action. Our actors need to get something out of it. Otherwise, why bother?

There is an undeniable truth in the concept. It is heavily user-centred. It tells the story circling the user. One needs to pry all the compassion from within to be good at writing user stories.

The definition of a user story

Let’s shift our attention to a tangible definition of the phrase.

In Agile, where user stories find their origin, they serve the purpose of describing an interim goal that contributes to the overall end goal, however vaguely stated. User stories belong to a bigger cause than themselves and are:

• informal
• easy to understand
• non-technical

Their meaning and form align greatly with the Agile Manifesto which puts people from all walks of life first.

Another role of a writing user story is to articulate how the work will provide value to the end-user. Remember, it is all about the user.

I believe user stories can be extracted from the agile software development framework and applied in other environments. For example, a supermarket could ponder over how to space out the aisles so that shoppers can reach checkout quicker. Doesn’t that constitute a user story? In my opinion, it does.

I prefer to look at writing user stories as conversation starters. They should be intriguing enough to pull people in and detailed enough to keep them around.

While researching the topic, I found an instance when someone declared agile user stories as placeholders for conversation. I beg to differ. A placeholder means to carry little or no semantic information. The Collins dictionary also states that placeholders are temporary. I would say these terms are far from accurately describing a user story.

Three C’s – Card, Conversation, Confirmation

Frankly, I haven’t come across that formula prior to writing this. Nonetheless, I think it makes the article more complete, so I decided to include it and learn why doing it.

3C’s describe the core components of an agile user story. The concept was proposed in 2001 by Ron Jeffries (one of the Agile Manifesto inventors) to help to distinguish social user stories from documentary requirements practices such as use cases.

• Card. It is a post-it note, or any note card, where you can write your story. It can also be used to leave annotations, story points, and so forth.
• Conversation. It contains details behind a story that came out from a discussion with the product owner.
• Confirmation. It confirms the user story has been delivered correctly and that all conversation points have been addressed.

If you have been writing user stories in the right way, you have already been utilising the definitions above – consciously or not.

Why does Agile need to write user stories?

User stories are direct descendants of Agile principles. They are enablers that allow participants to put the Agile Manifesto into practice. Perhaps the concept of writing user stories is older than Agile itself. It could have been that the term wasn’t yet coined and people had unknowingly played by the rules. To prevent the article from spiralling into the chicken and egg discussion, I will move on. But it is an interesting thought.

The pressure is on. If you do not follow the 12 rules from the book, you end up in the proverbial Agile jail. (You shouldn’t mess with the Agile police.) These time-tested directives are clear-cut and hard to misinterpret which makes them approachable and appealing. Be warned, they are effective only if followed to a letter by everyone involved. I learned the hard way.

A project powered by Agile principles is off to a good start. It embraces the framework which promotes collaboration, interaction, sustainability and flexibility. However, these proven rules come at the cost of certainty, which is a thorn in the neck for businesses on the receiving end. What am I going to get if I commit? They ask. The answer is not what they want to hear.

An open-ended approach and harnessing change mean that you cannot plan far into the future. That alone, if not explained properly, can be a deal-breaker for many investors. They struggle to wrap their heads around an idea in which the project objective is clear yet no fixed plan will get them there safely. It sounds a bit counterintuitive, and perhaps like a smokescreen for a scam, does it not?

While the Agile Manifesto remains defenceless in that regard, there is hope. It arrives with an army of tangible metrics, strict schedules and tools for delivering a body of work regularly. These weapons make things happen and keep stakeholders at bay.

User stories are probably the most dominant and influential weapon from the entire Agile armoury. That is because they break down big ambitious tasks into smaller, actionable units of work, and keep things in motion.

In light of that, there are several not-so-obvious benefits that come free of charge with user stories.

• They create shared understanding and use a common language between involved parties. Everyone can understand the requirements and challenges related to the technology
• They are value-based meaning any discussion or decision focuses on bringing the most business value to the doorstep as soon as possible.
• They keep the team’s morale up by allowing for quick wins and maintaining a sense of progress.
• They stimulate the team’s imagination and boost the team’s creativity by explaining problems in a compelling, benefit-oriented way.
• They inspire collaboration by getting members of the team involved from the get-go. That way they feel valued and included in the decision-making process.
• They draw a clear line in the sand between business value (Why? Who? What?) and technical details (How?)

One extra thing to keep in mind going forward is that the user story text is far less important than the conversations we have.

Without a tool like a user story, Agile becomes a wishy-washy concept that you cannot act on. We better give them credit when it is due. Thank you, User Stories.

When should you write user stories?

Naturally, the answer almost involuntarily rolls off the tongue. You should write user stories when you work in Agile. (That would be a darn short section of the article.) However, the response does not satisfy my curiosity, so I want to delve a little deeper.

Recalling the Agile armoury for a moment, it hinted that user stories were not the only available weapon around which you can organise a project. You see that is a moment when it gets mind-boggling. I truly struggled to understand the differences between alternative options because the lines get blurry, and I was on my own to figure it out.

There are epics, stories, themes and initiatives. You will also hear about features, tasks, subtasks, issues and bugs. Plus you can take a lead and create your own types. For example, we also have improvements and blockers. Tread carefully as the Agile police are near, though.

So, how does one know when to reach for a user story, and when for something else? At the risk of your disappointment, I will not explain each of those in this article as I want to stay on the point. I recommend you do your own research to get a better picture. Still, in the hope of remaining useful, I will zoom in on the most common misunderstanding: is it a user story or an epic?

Epic is a bigger user story. Objectively, this is as helpful as last year’s snowfall. (I am clearly not at my best but bear with me.) As I said, Agile does not care what befalls the bigger category. But the residents of House of Agile rush to the rescue with prescribed medicine. 

A user story should not take longer than a single sprint to complete. If it does, it is no longer a user story. It is an epic.

Of course, cynics might bolt in with their spruced-up intellect and rebel against the idea: why not break that user story into two smaller user stories? I apologise, but I wave the white flag here.

Who does write a user story?

Most likely a Product Owner. It is a person who acts as a glue between stakeholders, including customers, business managers, and the development team. They ensure the goals are clear and the vision is aligned with business objectives. It is a tough job if you ask me.

But not all teams are lucky to have Rocky Balboa on board.

Smaller teams (define smaller, right?), can employ a project manager, a business owner or even a developer for the role. (Although, technically, developers should not ever write User Stories if we were to stick to the rules. Oops, I hear sirens coming.)

Keeping it cosy has its advantages. First of all, there are fewer people to satisfy, so conversations tend to be concise. Secondly, projects are not yet high in complexity level. Thirdly, a faster flow of information tolerates mistakes because it detects them immediately. Even if an error slips through the fingers, you can turn your head to the left and talk to the person who made the boo-boo.

Dawid, that guy from our team, who mainly handles content creation and SEO, smashes it as a Product Owner. He is highly logical (his IQ test result would shatter your self-worth), he has a great attitude towards stakeholders and his planning skills are second-to-none. 

Who do you think is your Dawid?

What makes a good user story good?

We are getting to the point where we can apply the prior knowledge to practice. We already know that a good user story invokes conversations and that they revolve around the user. We know our three C’s. Regardless, there is one more blob of knowledge that I want to impart. I discovered an intriguing, almost not fitting, side to a user story. To be precise, happy and unhappy paths.

Clearly Agile is about logic. It is a framework to solve problems in the most efficient way, so how come we are discussing emotions? We mentioned compassion, but happiness? From the beginning of our civilisation, philosophers have been losing hair over its definition. How are we to trust Agile to come up with an answer? Worry you not. Here it is.

A happy flow explains the condition in which nothing ever goes wrong. A utopia, if you allow. (Another hard-to-come-by state. Fight fire with fire, I guess.) Conversely, an unhappy path brings forth a situation in which things go down the drain. As a careful reader could expect.

Let us take a login situation as an example.

In a happy scenario, an already registered user remembers her credentials, enters them and submits the form. As a consequence, the system satisfied with the input proceeds to authenticate the user and opens up the client area. Great!

On the other side of the spectrum, the same user forgot her login details, so she requests a reset password link. It never arrives. A frustrated user tries to remember her credentials, but uses up the three attempts and locks herself out of the account. Next step? Contact the support. (We have all been there; show some empathy.)

Why bother? It offers an interesting take on splitting individual stories into successful and failure scenarios. Apart from having independent Acceptance Criteria, you might decide to deliver them in multiple sprints. Not all situations call for such deliberations, but it is better to be in the known. As always see it through your prism of priorities and decide what is best for the project’s well-being.

How do we use what we know?

User story examples

It is only fair to start by discussing the user story template.

As per usual, there is no right way of writing user stories. As long as ticks all the boxes, you are in the green. Here is the most commonly used formula to get you started:

As a <user>, I want to <action>, so that <benefit>.

• The “As a…” indicates the actor doing the action.
• The “I want to…” explains what the actor wants to accomplish.
• The “so that…” points to the motivation behind their action.

That approach is occasionally called the Connextra format which originated with an Agile coach Rachel Davies at an English company Connextra in the early 2000s.

As you dive into the world of Agile, you will encounter other variations of the same template. For example:

• In order to <benefit> as a <user>, I can <action>
• As <who> <when> <where>, I <want> because <why>

(I was not aware of the last proposition, and I cannot quite work out how to turn it into an example yet. I left it in for the sake of making the article as complete as I can.)

To bring it home for you, I have pulled a few real user stories from our array of projects.

• As a user, I want to read about existing customers so that I can learn more about their experiences.
• As a user, I want to book consultations so that I can start using the service.
• As a user, I want to publish my profile in the directory so that I can get more clients.

While templates are widely known, they are often outgrown by experienced Agile teams. If you are already an Agile addict, you might want to limit writing user stories to bare bones:

• Administrators can ban naughty users.
• Website visitors can download resources.

Nonetheless, the templates serve as training grounds, reminding people in conversation about the basics. Nothing wrong with that.

What about Acceptance Criteria?

This article would not be complete without skimming over the Acceptance Criteria. I will only elaborate on the basics to not cause information overload (MVP, baby!)

Acceptance Criteria are a set of conditions that need to be met to consider a user story done. They are a desirable part of every user story. For the good of your own sanity, they do not follow any particular formula and you will not be at risk of hearing the banging at your doors in the middle of the night.

At conception, writing user stories did not include Acceptance Criteria. Eventually, people started to understand that just having the story statement was not enough to determine completion.

You are free to choose the level of detail attached in the Acceptance Criteria box. You can start simple with “make it convenient to use” or push it level up to a more diligent definition. If we take the first example into consideration, its Acceptance Criteria could look like this:

• The user can find 10 reviews on the home page.
• The user can access 3 case studies from the website navigation.

Examples of bad user stories

In spite of the guidelines, it is possible to join the dark side. I believe that there are two main pitfalls that await us.

First, we assume wrong. We do that all the time to cope with reality, so it is only natural that the habit sneaks into Agile. For example, a user story that starts with “As a user, I want to log in, so that…” presumes that the user enjoys the action of authenticating. Trust me, we do not. We would rather never have to do it again.  

Potentially, logging in is a functionality a user has to face to achieve a goal. However, it does not constitutes the goal itself, so, therefore, it is not a user story (or at least a good one). We need more compassion than that, readers!

The second misuse of a user story is when it dictates the functionality. User stories should always remain non-functional, informal and understandable by everyone. For the sake of example, let me reword my first example of a good user story to read like this:

• As a user, I want to read a tooltip next to an existing member so that I can learn more about their experience

There is a subtle but important difference. The action has now transformed into a feature-creating vehicle. Not only does it raise questions but also takes away the freedom from the team to find the best solution. At that stage, for all we know, the user wants to enquiry about the existing members. The “how” is a separate step that is not relevant here. (Refer back to drawing a line in the sand under the benefits of writing user stories.)

By now, we know why user stories are a good idea, but what about situations in which they do not fit well? How do we manage exceptions?

Exceptions

Some teams might want to surrender to common sense and not put these kinds of technical requirements into the user’s voice. You might occasionally stumble upon a task that is difficult to describe in terms of user stories. In that case, you can identify and add these logical chunks to a backlog. I would encourage you to check with your Product Owner that they understand what they mean.

It is a common practice for smaller projects or among one-man-bands to follow. As long as these chunks represent a stand-alone piece of functionality, then you are good to go.

For example, it would be overkill to write the following tasks from the user’s perspective:

• Install Google Analytics on all pages
• Change the colour of the button in the navigation bar

The final word from me is that if the user story format works for your team, do it. If there is another option that the team prefers and it still leads to shared understanding, do it. As with all things Agile, the only right way is what works for the people involved in the work. It is all about humans and interactions.

Once you give it a go, drop the user stories in the comments and we’ll give you tips if needed. I’m sure you’ll ace it after reading this article, though 😁

Arigatou gozaimasu.

T.