Subscribe to Email Updates

Discovery Workshop Download

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

Posted by Eric Skinner on August 11, 2016

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:

blog-bug-reports-bad_ticket.png

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:     

  1. Log in on an iPhone via Firefox

  2. Navigate to My Inbox

  3. Click, Search Current Mailbox and type in “allcompany@software.com

  4. 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. 

blog-bug-reports-good_ticket-486750-edited.png
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.

Tell the story of your startup city
Eric Skinner

Written by Eric Skinner