Agile eXamined: User Stories

by Dan Greenberg

User Story example from Kent Beck and Cynthia Andres

from Kent Beck and Cynthia Andres. Extreme Programming Explained: 2nd Edition Embrace Change. Upper Saddle, NJ: Pearson Education (2005).


What is a user story? Is it the same as a business requirement?

A user story is written by the customer, or from the customer’s perspective, and describes how they would like to interact with a product or solution. User stories provide important context and often express a desire for functionality that does not yet exist.

User stories are very different from requirements. Requirements tend to prescribe a specific implementation or solution approach; they are often “closed” and provide little information about the user and their needs. Effective user stories center on the user and are deliberately open-ended. They intentionally keep the team focused on the problem space, allowing them more creativity and flexibility in how they address the user’s need.

How detailed should a user story be?

User stories are intended to be placeholders for a conversation; they are like pointers to data and not the data itself. User stories should provide enough detail to allow team members to understand the context and the need, but they should not be overly specific. If they are, they will hinder creativity.

Ideally, a user story leverages the three C’s: card, conversation, and confirmation. It’s written on an index card (keeps it from being overly verbose); it prompts a conversation; and, when it is done, the functionality can easily be confirmed.

By reviewing a story and conversing about it, team members will conceptualize the need and develop a sense of the associated effort, complexity, and uncertainty. In some teams, this leads to a sizing effort. In others, it may lead to a more nuanced discussion. Regardless of the specific approach, well-drafted user stories and the conversations about them allow team members to decide whether to take the story on, address risks through a spike, or break the story up into incremental deliveries.

Do I need to write a user story to document everything I do?

Teams should track and visualize all their work, however, that does not mean everything should be a user story. A good indicator is whether or not the work requires a conversation.

Should you, for example, write a user story about powering up your laptop in the morning? Probably not.

What about rewriting the build script for your team’s CI/CD pipeline? Probably so. The whole team should have the opportunity to talk about a big change like that.

What are some user story templates that teams find helpful?

A common format for a user story is:

“As a __________, I need ___________ so that __________.”

The most important pieces of this structure are the “so that” (why do I need this?) and the “as a” (who am I?). These add valuable context that can influence the approach to implementation.

For example, consider the following:

  • Example 1: As a journalist, I want a camera feature on my phone so that I can capture photos while covering events without bringing along extra equipment.
    • In this case, there is a desire for a lightweight way to capture images.
  • Example 2: As a researcher, I want a way to capture images and store them on my cloud drive so that I can go back through documents once I am back at the office.
    • In this case, several needs are implied:
      • High resolution, so the images can be read later.
      • Some form of data transmission, from the camera to the cloud.
      • A way to classify and organize the images.

It’s easy to see how a conversation can help address questions, draw out misunderstandings, and provide even more valuable context.

What about acceptance criteria?

User stories are often augmented by acceptance criteria, details that help ensure a story has been delivered correctly. These can be written as Given-When-Then statements. Given-When-Then is a core aspect of Behavior Driven Design (BDD).

Here is a simple example:

  • Given that a customer’s account has a balance of $100,
  • When the customer makes a withdrawal of $40,
  • Then the customer’s account should have a balance of $60

This format is particularly useful for determining when a story is done. Tools can help by processing Given-When-Then statements and turning them into automated tests.

If Given-When-Then proves overly prescriptive, acceptance criteria can be written more directly:

  • Test that a customer’s account balance reads $60 after a $40 withdrawal when the customer started with $100
  • Test a few other scenarios similar to the above

As with any practice, it’s all about what works best for a particular team.

Let us know your thoughts on user stories! How are you using them with your teams?

Read more in our Agile eXamined series.