What is Story Elaboration?

It is common for teams to struggle with writing user stories that clearly communicate things such as:

The target user (persona or user type)
The goal or goals the target user seeks to achieve
The reason it’s important to the user to achieve the particular goal(s)

The process of user story elaboration is where teams have a shared understanding of what things they need to include in each user story.

What’s the Benefit?

The benefits of elaborating user stories based on a known and repeatable pattern include improved understanding of:

The business value
The business priority
The relative effort (size)
What “done” looks like
What technical approach to take

When?

Teams can benefit from spending time on story elaboration at any time. The situations in which story elaboration is most common include:

Backlog Refinement
Sprint Planning
Release Planning

Who Attends?

A facilitator (often a Scrum Master or an Agile Coach)
A Product Manager or Product Owner
All of the team members

Note: There is a common misconception that the sole responsibility for writing user stories rests with a Product Owner (or a proxy for the Product Owner). Although it is common for Product Owners to draft user stories, it is important for team members to be involved with writing and refining user stories, because when the team is engaged in this activity, it improves the likelihood that everyone has the same understanding of what is to be built, why it is to be built, and how we know when it’s done.

Inputs

Definition of Ready
Prioritized Product Backlog Items (PBIs)
Product Roadmap
Product Goal

Outputs

Stories meeting the Definition of Ready

Preparing for Success

To have a successful story elaboration conversation, it’s important to have:

At least one person who can articulate the “voice of the customer” (often a Product Manager or Product Owner)
Multiple people who are familiar with the technical domain in which the team is working (ideally, all team members are present)

Execution

Let’s start by describing components of “well-articulated user stories.”

Components of Well-Articulated User Stories

Individual sections follow on each of the main components of a well-articulated user story:

Title
Description
Priority
Size
Acceptance Criteria
Technical Approach

Story Title

Just as is the case with other types of titles (aka headers), a story title should be short, because short statements …

Are easier to capture on physical media, like index cards or post-it notes
Are easier for team members to verbally reference when looking at multiple stories
Are easier for team members to parse when scanning for stories in a tool such as Jira

Note: The story title maps to the “Summary” field in Jira.

Story Title Format

The following format is recommended for story titles:

<role> <action> [<context>]

For example:

Primary applicant enters passcode

where …

<role> = Primary applicant
<action> = enters passcode

Note: <role> and <action> are required, whereas <context> is optional in the title. For instance, when there are many user stories with similar titles, the addition of context can help distinguish between them. In the example above, perhaps it will be possible for the user to enter a passcode in different places in the application being built, or perhaps there is more than one kind of passcode. In such cases, adding context could add clarity, such as “Primary applicant enters passcode on <page type>, or Primary applicant enters passcode <type of passcode>.

Story Description

The canonical format for a story description is as described below. Here are some things to keep in mind when writing the story description.

Think in terms of inputs and outputs:
- What data (or other type of input) does a person or system enter or inject?
- What data (or other type of output) results from that input?
- How will we test it?
Think in terms of vertical slices:
- What is the thinnest possible slice that delivers value?
- What can we do to ensure we are exercising multiple layers? (rather than having separate user stories for different horizontal layers, e. g., UI, database)
Think in terms of the smallest number of words that can convey the story intent:
- “Don’t let the perfect be the enemy of the good” (write something down and move on; you can always update it later)
- You may later realize that this user story is either unnecessary or has to be split into smaller pieces (all the more reason not to spend too much time on writing any user story!).

Note: The story description maps to the Description field in Jira.

Story Description Format

The canonical format for a story description is

As a <role/persona/user type>
I want <goal or action>
So that <desired result from goal/action>

For example:

As a primary applicant
I want to enter the passcode I received from my representative
So that I can access my benefit request and verify the information

Story Priority

The priority of a user story is reflected by its relative position in the Product Backlog, and by its relative position in the Sprint Backlog (user stories closest to the top of the list have the highest priority).

Note: The Jira Priority field provides many additional options that can indicate relative importance of any given work item. This cheat sheet does not cover usage of the Jira Priority field.

Story Size

When Agile teams estimate size, they employ “relative estimation.” It’s called relative estimation because we focus on the relative size of thing A relative to thing B, thing B relative to thing C, and so on.

Note: For a particularly rapid estimation technique, see Affinity Estimation.

Story Size Format

For teams that use story points to estimate, it is most common to only use numbers that are part of the Fibonnaci Sequence for story point estimates: 1, 2, 3, 5, 8, 13 …

Why use the Fibonacci Sequence?

As anyone who has spent any time building software can attest, it is a difficult proposition to precisely estimate the size of anything we build, and the larger the size of the batch (be it a feature, or a release), the greater the uncertainty and the risk. (Keeping batch size small helps minimize both complexity and risk.)

It has become popular to use the Fibonacci sequence because doing so reinforces the notion that estimates are never exact. For instance, when we consider a user story that has been sized as a 3-point story, and a user story that has been sized as a 5-point story, all we can say with any level of certainty is that based on what we know right now, it will be more work to complete the 5-point story than it will to complete the 3-point story. (By way of comparison, if we are looking at a 3-point story and a 6-point story, it’s more likely we’ll fall into the trap where we assume the 6-point story is exactly twice as big as the 3-point story).

Another appealing aspect of using the Fibonacci sequence is that the bigger the numbers get, the larger the gap between them, which serves as an indicator that uncertainty and risk tend to increase rapidly as work items get larger.

Story Acceptance Criteria

For any user story to be considered Done, it needs to satisfy its Acceptance Criteria, AND it needs to align with any global provisions that exist in a Definition of Done.

A simple way to articulate the purpose of Acceptance Criteria is this: Acceptance Criteria guide the testing strategy, enabling us to demonstrate (via tests) that the user story achieves what it is intended to achieve.

Note: Acceptance Criteria often do not map directly to a particular field in Jira (depending on how Jira is configured). A couple of examples of ways to include Acceptance Criteria in Jira include:

Add a text field to the Story issue type (in Project Settings) and call it “Acceptance Criteria.”
Manually add the Acceptance Criteria to the Description field

Story Acceptance Criteria Format

There are multiple ways to write Acceptance Criteria.

Note: For the purposes of this Play, we only describe the “Test that… ” format for Acceptance Criteria, which has the simplest syntax. Test that …

Here are several examples of tests written in the Test that … format:

AT-1. Test that when a user enters an incorrect old password, they get an error message indicating incorrect credentials

AT-2. Test that three incorrect submissions of the old password within 1 hour results in the user being logged out from the system

AT-3. Test that the order confirmation contains:

Order number
Estimated arrival date
Customer service email address

Story Technical Approach

In contrast with the story headline and story description, which focus on the who, what, and why, the technical approach (in conjunction with the Acceptance Criteria) focuses on how.

Note: In general, artifacts that fall under the technical approach map to Jira as attachments, links, or Sub-tasks.

Story Technical Approach Format

Because the technical approach can vary significantly, depending on the product, it is difficult to specify a particular format for the story technical approach. Here are some general guidelines:

It is common for multiple stories to reference the same artifact or set of artifacts (for instance, a flow diagram, data flow diagram, or sequence diagram). As long as the team understands where the artifacts are located, and what the contents of the artifacts are, it’s not always necessary to attach such artifacts to the story (but it is often helpful to link to their location).
By way of contrast, wireframes or mockups are artifacts which often are specific to a single story, and as such, it’s a common practice to attach or embed such artifacts in the story (linking to such artifacts is often acceptable too).
Some teams outline the technical approach they are going to follow to implement a story as a series of steps. Each step is often referred to as a “Task,” and the process of figuring out what those steps are is called “task decomposition.” (in Jira, it is common to use Sub-tasks for this purpose).

Note: Jira (and many other tools) support the practice of entering time (typically in hours) associated with tasks. A large number of Agile practitioners consider the entry of task duration (i.e., “burning down” the hours) as a form of waste. In other words, the most important thing to focus on is task completion, not on spending time specifying that a particular task is half-done about lunch time, and three-quarters done at the end of the work day.