gears

In our first post about what makes a good user story, we talked about how good user stories follow the INVEST acronym…

(they’re Independent, Negotiable, Valuable, Estimable, Small, and Testable). In this post, we’ll talk about guiding principles in story writing and how to make user stories clear and easy to estimate.

What to Include in Your User Story

If you’re new to user stories, it might seem like user stories are just a bucket where we throw all the details related to a chunk of work. But there can be a surprising amount of finesse with user stories. From our first post in this series, we learned about the INVEST attributes of a good user story. When it comes to the details of a story, there’s also a better way to make your story readable.

The first thing to understand about the process of story writing is that you’re going to receive a mishmash of details from stakeholders. They might come from a variety of sources like your Product Owner, business stakeholders, a QA team, or engineers on the team, and they’ll have input on:

  • Business-related vs. technically-inclined requirements
  • Functional vs. technical details
  • Strategic vs. tactical execution of the product
  • Shallow vs. deep scope
  • And so on

Writing a story is a process of filtering content of varying levels of detail from many sources. To borrow from Neal Stephenson:

A story writer’s goal is to ‘condense fact from the vapor of nuance.’

It’s up to you to filter out the cruft so that your story emerges with a coherent narrative that gives the team enough to get started. A good story writer can listen in any discussion with any audience and identify and transform the following pieces of information into a coherent story:

  • The User Story
  • The Narrative
  • Assumptions
  • Requirements, AKA Acceptance Criteria
  • UI / UX Requirements
  • Technical Requirements or Notes
  • Testing Notes
  • Open Questions

When it comes to how to arrange the above in your story, there is no prescribed template; it’s more important to understand the different parts of a story you might encounter. Templates for user stories can also lead to overreliance on the layout and discourage critical analysis. So, your focus should be on guiding your user down a funnel of information:

  1. Start with the user story and the narrative first. Establish the context and the user’s goal in layman’s terms.
  2. List the detailed requirements that will fulfill acceptance of the story. You can’t skip this step.
  3. Optionally, add your technical implementation and other notes that may be relevant only to specific team members (QA, UI/UX, etc.).

How Much to Include in Your User Story

How much detail should you include in your user story? Answer: it depends.

First and foremost, your story must include all of the requirements that your Product Owner feels will satisfy the story and its acceptance.

As for the rest, the rule of thumb is: give the team enough of what they need to get started. The story need not be 100% perfect and fully fleshed out. If you work with a mature or healthy agile team, they’ll understand that requirements and stories change all the time. We won’t always know all the requirements. Business value changes. There will always be some details — whether technical, functional, or other — that the team doesn’t think of during estimation but remembers later during execution.

An agile team understands and expects change. While there are limits to when you can change a story, the guiding principle is that the team accepts that the user story doesn’t need to be prescriptive and that we’ll add information as the story progresses. Otherwise, trying to nail everything down in a story can lead you down the path of too much analysis and a too waterfall-like pattern.

Screenshots: Include ‘Em!

Whenever I walk the team through a user story during a story estimation meeting, the first thing I invariably reach for — even before I summarize the user story — are mockups or screenshots. If you ever have these available for user stories, it’s a no-brainer to include them. Here’s why:

The team is hearing about your story for the first time, and they likely have zero background on all the conversations that have gone on with the Product Owner. Giving a team a visual of what they’re going to build is always the best way to start when you have to establish context around a story. The saying really is true – showing the team a picture of what your user story has to do is worth a thousand of your words that the team has to read.

Describe this to the team with words.

A flowchart
Courtesy of xkcd

Give the team the big picture to start. The majority of folks are visual learners — people just process images a lot faster. So show the team a mockup or screenshot that they can mentally retain and then dive down into the specifics like the requirements of your story. Otherwise, you’re relying on the team to collectively imagine the same thing while processing everything you explain about a story’s nuances and requirements – all while they’re trying to figure out a technical solution at the same time. Just show the team a picture.

That wraps up this post on fine-tuning your story. Stay tuned for our final post in this series, where we’ll get into the tricky business of debugging user stories. Wat?


This article is part two in a series of three articles about good user stories.
Did you miss our first post or want to jump ahead to the final post?