Written communication is hard. Bugs and stories too often lead to people having to unnecessarily ask someone to explain what's been written because it's vague. There's such a thing as too much detail, but too little, unclear information is more common.

This article doesn't cover all about writing good user stories or bugs. It focuses on a few practices that I've found help the most.


The most important parts of a bug report are A) the steps to reproduce the problem, and B) clarity of what the problem is.

There are many audiences for bugs: the user who's reporting, the developer who's fixing, the product manager or business analyst who's communicating the bug from the user to the team.

All of these audiences have different mental models of the application and often assume others know what they do. How do we make sure the steps are clear? Here's one tip I like.

Write the repro steps as if you were training a new employee

Here's how the initial user (who could be a developer or product owner, really anyone) might initially desribe a bug.

Help! When I search for a customer it should show me the last modified date but isn't.

Clarifying this bug may require a few messages or, ideally, watching the person do the work. The bug report might end up like this.

TITLE: Solaris Activium Search not showing last modified for Nevada customers

1. Open Solaris Activium
2. Choose Menu > Search > Customer Search
3. Enter last name "Calypso", first name "Bernard" and Search. Note she lives in Nevada.

Expected: A last modified date within the last few years
Actual: 0000-00-00

4. Enter last name "Chattergee" first name "Parag" and Search. Note he lives in Maine.

Actual: 2019-03-24

[screen shot]

They're only seeing this happen with customers who are in Nevada, but 
haven't tested all states.

(optional if obvious from the bug.)

Last modified date is shown for customers in all states.

What helps the person who opens the bug?

  • Which system/app is involved?
  • What are the exact steps the user performed?
  • What was expected? What was actually seen?
  • Sometimes a screen shot helps

"Exact steps the user performed" is important. Often someone familiar with the application will try to reproduce the problem but using different steps, leading to "I can't reproduce" confusion.

Note that while the user might consider the bug fixed if Nevada customers show last modified, the developer should have realized other states could be affected, leading to the more thorough acceptance criteria.


Stories, aka "user stories," are used for planning. They should contain the least detail necessary to understand what the story's about and how to know it's done. They promote conversation. A story will likely change as it gets closer to release.

There are several techniques to help define the story's value. A common one is the template "As a [Role], I [need/want], because [value]. Here's an example.

TITLE: Implement Solaris Activium login reset 

As a User, if I've forgotten my password I want a 
way to easily reset it so I can quickly get back to work.

Today, if a user forgets her password she has to submit a support 
ticket. Reviewing the last six months of help desk data, it takes 
an average of four hours for the password to be reset. These users 
often have deadline-based work, so those delays have a serious cost.

[jj] I think we can do this using the standard forgot password pattern.

The new flow is

*   User clicks "forgot password" on login page.
*   User enters email address and submits.
*   Email arrives in under a minute with link to reset.
*   Link opens a page to enter the new password twice. Password is validated.
*   After submitting valid password, user is immediately taken into app.

The key elements above are:

  • We know who, what, and why, stated as simply as possible
  • We understand the business value, probably a result of discussion with the user and developers
  • Developers can capture key discussion points.
  • The story is testable, and the test is simple.

Wrap Up

Hopefully this is useful. What both bugs and stories boil down to are:

  1. What are we trying to do?
  2. Is it clear to everyone?
  3. How will we know it's done?

Concise, clear sentences make a big difference. This all takes practice but pays for itself quickly.