LookFar Labs11 August 2016

How to Write Bug Reports: The Good, The Bad, and the Ugly

You’re testing your product and found a bug before your users did.

Success! Send it off to the developer, and it’ll be fixed. Mission accomplished, right?

…not really.

Finding a bug is half the battle. Want to repeat yourself, send in tickets developers dread, and–ultimately–end up with everyone wasting time and being even more frustrated than when they started? Then, send ’em something like this:

Seeing an issue written like this only leads to more questions. “What, specifically, isn’t working about it?” “Where is it broken?” “How did you break it?” Answering these questions the first time around saves everyone time: time that you wish you weren’t spending explaining bugs, and time developers wish they weren’t spending asking about them.

Creating a bug reports should be like writing a recipe. It should tell you what you’re cooking, a list of ingredients you need, easy to follow steps, and what you can expect at the end.

The result is a template consisting of a Title, Environment details, Steps to Reproduce, Expected Behavior, and the Actual Behavior that’s happening. Let’s dive into some specifics, give some examples, and talk about how to write a bug report the right way, the wrong way, and the ugly way.

Title

A title should be an easily digestible, one-line synopsis of the issue. A bug report is something your project team will use to reference the issue, so keep it concise and informative.

The Good: Searching for an Email by Sender displays an error and closes the application

The Bad: Searching for an Email and the application crashes

The Ugly: Search for an email is broken

Environment

As technology continues to march forward, so do our options for interacting with software and the web. For QA, developers–and yes, even users–this means we need to be specific about what we’re using when recreating issues. Using a specific file or in-app configuration? Include that too.

The Good: iPhone 6 / iOS 9 / Firefox 47.0.1

The Bad: iPhone

The Ugly: [Blank]

Steps to Reproduce

Providing a step-by-step process of what you did to find the issue gives direction to your users. Each step should be a specific and separate action. If you’re doing it correctly, your reader should be able to easily navigate through your software. A good practice here is to go through the steps you wrote, line by line, making sure every detail is written out. This gives you the chance to fine tune and add anything you may have forgot the first time around, leaving no room for confusion.

The Good:

Log in on an iPhone via Firefox
Navigate to My Inbox
Click, Search Current Mailbox and type in “allcompany@software.com”
Click Search

The Bad: Log in and search for a sender

The Ugly: Search for emails

Expected Behavior

What were you expecting to happen after your last step? If you’re working off requirements, acceptance criteria, or a user story, reference it.

The Good: All emails from, “allcompany@software.com” should populate the search results, per Acceptance Criteria 3.2a

The Bad: Emails from the sender show up

The Ugly: Emails appear

Actual Behavior

What actually happened? Did you receive any error messages?

The Good: A “500 Internal Server error” popup message appears and the application closes

The Bad: An error pops up and crashes the application

The Ugly: It crashes

Now, let’s put all those components together…

…and we wind up with a well-defined, easy-to-reproduce bug report. Send your development team something like this, and you’ll be filling in a bunch of extremely important blanks for them and saving a bunch of valuable time in the process.

Wrapping Up

Fixing a bug starts with reproducing it. If you can’t reproduce it, how will you know if it was fixed? Developers can try to make changes and updates to what *could* be the problem, but unless you can make a before-and-after comparison, you can’t truly be certain it’s resolved.

Providing all the pertinent information upfront leads to bug tickets that everyone loves. Detailing issues does take more time and effort, but it saves time and frustration in the end. Good bug reports = happy developers, and happy developers = better products.

Written by

Eric Skinner