Be Good To Your Devs: Write User Stories That Are Easy To Understand

October 28, 2014 Joanna Beltowska

Product Teams Spends Lots of Time With User Stories

As a Product Manager (PM) on an agile team, you have two primary means of communicating with your team members: face to face conversation and user stories.

You’re going to write tons of user stories and your developers are going to pick up tons of stories. You might know from your own experience that it can take some time to learn how to write good user stories. You probably also know that even small improvements to the format and the content of your user stories can bump up your team efficiency and happiness significantly over time.

Following the INVEST framework and using a good story schema will take you far. However, there are a couple of things you can do that can take your story writing skills even farther.

The Best User Stories Can Be Started Immediately

A good user story accomplishes 3 things:

  • It defines its scope
  • It explains and justifies the user value that it will contribute
  • It enables the developer to quickly understand the story so she/he can start implementing it

While we often talk about how to nail the first two aspects of a good user story, we rarely talk about how to get the third aspect right.

The key is to minimize what I call the Time-to-Understand variable. This is the time a developer pair needs to invest in reading and understanding the story before they can start implementing it. This typically involves speaking to the PM to clarify parts of the story and the background for the story or getting access to all the assets and information needed to implement the story.

A non-trivial frequency and amount of Time-To-Understand is going to drive down the efficiency of the team through disruptive context switching and unproductive Iteration Planning Meetings. It’s also going to reduce the overall happiness of the team: developers want to spend their time building software, not trying to interpret user stories.

5 Tricks to Make Your Stories Faster to Understand

Here are my best tricks for writing stories that minimize an engineer’s interpretation time so that s/he can start writing code as quickly as possible:

1. Use real examples to capture edge cases

In your acceptance criteria, describe an actual use case using real examples and data.

Not only does this express the anticipated behavior more clearly and more concretely than if you write in general terms, it will also help you identify additional use cases and edge cases more easily.

For instance, you might have written a story about how a user should be able to add a product to a shopping cart by clicking the “Buy” button on the product page. What if the shop sells products that have options or are customizable? The shopper would have to configure their product before being able to put it in their cart. If you write the story using real product names, it’ll remind you to think about whether the product you’ve chosen is a representative use case or not.

Consider the following examples for an ecommerce site that sells beauty products:

Given that I’m a logged in user
When I click the “Buy” button on a product page
Then I should see my cart’s item count increase


Given that I’m a logged in user
When I’m on the product page for “Perfume Gift Set”
And I click the “Buy” button
Then I should see the item count for my cart increment by 1

When I’m on the product page for “Volumizing Mascara”
And I click on the “Buy” button
Then I should see a helpful hint asking me to select a color first

When I select the option “Black” in the “Colors” section
And I click on the “Buy” button
Then I should see the item count for my cart increment by 1


2. Visually format your story so that it’s easy to scan

Pivotal Tracker users Markdown which means that you can create a helpful visual hierarchy and flow in your story descriptions. This is especially valuable with longer and more complex stories.

Compare these two examples:




By separating the motivation from the acceptance criteria, giving each chunk of important information its own line and labeling each scenario, the story has become vastly more readable.

3. Separate the meat of the story from the details

This one’s pretty straightforward: write the story description to express the gist of the story. Pull out URLs, references to visual assets, copy and related tasks from the story description. Instead, use footnotes to create references to this information.

For instance:


4. Put the CSS for your mocks in your mocks

If your story introduces a design change, add the information necessary to implement the new styles to the mock. Putting the new styles inside the visual reference (rather than in the story description) shortens the distance between related content (the visual reference and the implementation details), saving time and minimizing human error.

Take a look at these two example mocks:



5. Clearly define the story scope in the attached mocks

The mock you attach to a story probably represents several stories’ worth of work (for instance: an update to an existing feature or an entirely new feature). As such, the mock might suggest that the story is much more complicated than what it actually is which may lead to lengthy discussions about story scope at your next IPM.

To help your team out, circle the sections of the mock that belong to the story and cross out the sections that don’t. This will help the developers immediately understand the complexity of the story, enabling the team to quickly focus on what matters and get to talking about implementation (rather than story scope).



About the Author


Parsing JSON in Objective-C – Part 2
Parsing JSON in Objective-C – Part 2

In the previous article, we used TDD to parse JSON into our Person model and refactored the code under test...

When in Doubt, Leave It Out
When in Doubt, Leave It Out

I’ve rarely regretted cutting a feature, whether working with clients at Pivotal Labs, as an in-house produ...