Article image

Writing user stories

XC Staff

A user story is a short, simple description of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system.

Why do we write user stories?


When we write software, we want to keep the focus on our users. We want everyone to know the value of the work we do and why we are doing it. As such, we create user personas that represent the customers we'll serve. Each story is written from their perspectives.

Vertical slices

Stories include every layer of a system, for example, UI, services, and data. This is called a vertical slice. We do this so that we can deliver value sooner, and shrink the feedback loop so that we can continuously improve.

Aren't user stories just requirements?

No, user stories are not synonymous with requirements. A story starts as a placeholder for conversation. Its purpose is to to define how to help accomplish a user goal.

Stories have acceptance criteria which may include some requirements, but are typically focused on system behavior, not implementation details.

Who can write user stories?

Anyone can! They are just a placeholder for a conversation, remember?

The Product Manager will typically do most of the heavy lifting, but there are no restrictions on which team members can contribute to stories.

How do I write a user story?


Every user story starts with a description that explains what a user wants and their motivations. They typically follow this format:

I want
so that

Acceptance criteria

Acceptance criteria define the scope of the story. All acceptance criteria must be met before the story is considered complete. They are typically written in Gherkin syntax when defining system behavior:

Given <state/precondition> -- This is a pre-requisite, what has already happened.
When -- Something that happens (a user interaction or a system event).
Then -- What is expected to happen as a result of the preceding action.


INVEST is a helpful mnemonic for writing good user stories:

  • Independent (as possible) -- Enables flexibility on priority.
  • Negotiable -- Nothing is written in stone.
  • Valuable -- Must have clear user value.
  • Estimable -- If it can't be sized, it can't be prioritized.
  • Small -- Break down work into the smallest possible pieces so it can be delivered quickly.
  • Testable -- If you can't test it, how will you know when it's done?

Examples of good and bad user stories

Bad user story

As a product manager, I want users to be able to enroll in a Medicare plan so that I can boost conversion rates.

Given I am on the plan details page
When I click the "enroll now" button
Then take me to the enrollment confirmation page

This story is not focused on the end user, it is a statement of a business objective. The acceptance criteria is heavy on implementation details with references to pages and clicking and even button names. But it is missing the behavior -- enrolling the customer in a Medicare plan.

Good story

As Deb, I want to enroll in a Medicare plan so that my insurance needs are covered for next year.

Given I am viewing a plan's details
When I choose to enroll
Then enroll me in a plan
And display confirmation details

This story is focused on the customer persona. Acceptance criteria are clear and capture the system behavior without specifying how to implement.


[Pivotal Tracker](Pivotal Tracker)

Further reading

XC logo

Humana, Inc.

© Experience Center 2019-2023