macgram

What is a user story? Definition and example

A user story describes a need from the point of view of whoever benefits from it, in one sentence. It comes from agile methods, but it is also written during analysis, before the use cases and the data model.

The sentence

It almost always follows the same template: “As a [actor], I want [action] so that [benefit]”.

  • The actor says who has the need: a customer, a seller, an administrator. Not “the user” when you can be more precise.
  • The action says what they want to do, in their words, not the developer's.
  • The benefit says why. It is what settles things when two stories clash or one has to go.

What goes around it

  • A code (US01, US02…) to refer to it.
  • A priority (high, medium, low) and an estimate (2 hours, 3 days, points).
  • Conditions: what must be true before (preconditions) and after (postconditions).
  • The main scenario, step by step, between the user and the system, then the alternative scenarios.
  • Acceptance tests: an action and its expected result. Until they pass, the story isn't done.

An example

The online shop of the MCD page.

US03 · Place an order. As a customer, I want to check out my basket so that I get my products delivered. High priority, estimate 3 days.

  • Precondition: the customer is signed in and their basket isn't empty.
  • Main scenario: the customer checks out. The system shows the total and asks for an address. The customer enters it and pays. The system records the order and sends a confirmation email.
  • Alternative scenario: the payment is declined. The system says so and keeps the basket.
  • Test: basket of 2 products, payment accepted. Expected: an order with 2 lines, marked “paid”.

The nouns of a story often give entities of the data model (Customer, Order, Product), and its verbs associations.

A good story

The qualities of a story are often summed up as INVEST: Independent, Negotiable, Valuable to the user, Estimable, Small and Testable. A story you can't estimate is often too big: split it.

User story and use case

Both describe what the system does, at different levels. The story is a short, precise need. The use case groups several stories around one goal of the actor, on a diagram. Place an order is a case; checking out the basket, entering a delivery address or using a promo code are stories.

In the macgram editor, the User stories screen keeps the “As a… I want… so that” template, the scenarios and tests as tables, and copies everything as Markdown. Each story is tied to its use case, and the To check tab flags a story without a case or a missing actor.