Dave’s bug report don’t stink

Great bug reporting can make or break a project. Here’s how to make yours awesome!

TL;DR

An awesome bug report is always going to contain the answers to these three questions:

1. What went wrong?
2. What did you expect?
3. How did you make that happen?

You found a bug. Now what?

Imagine this scenario: you’re editing a document need to save it. You try to click the button to save your document but it doesn’t work. That’s definitely a bug. (Note: this narrative was intentionally left vague.)

While it may be tempting to shoot a developer an email saying something like “The save button is broken,” doing so is likely not going to be effective. My goal is that by the end of this post, you’ll know exactly why that is as well as what you can do to write bug reports that get results.

Let’s have a bit of fun and walk through an example of an unhelpful bug report and then look at how to improve it.

An unhelpful bug report

“Dave’s bleep don’t stink.”

Why it’s not helpful

Only expressing the negative doesn’t let the developer know what the correct behavior should be.

Ought his bleep stink? Who’s to say? We’re you expecting Phil’s bleep not to stink, but instead found Dave’s to be odorless? What do you even mean by bleep?

The one-liner report also doesn’t provide any help to the developer or tester after the bug has been worked on.

How can I test to see if his bleep still don’t stink? Has someone already fixed this?

All of these questions need to be answered which takes time. Unanswered questions will likely lead to either an incorrect solution or more bugs.

We can totally improve this!

Expected vs Actual

First, let’s include the expected behavior so that the developer knows at a high level what you were trying to do or what you wanted to happen. Also include what you actually observed. This compare-and-contrast helps explain the specifics of the problem. For example:

Expected: I expected Dave to make the bathroom stink.Actual: The bathroom smelled like clean air instead.

Now we have more information about what went wrong. No one needs to investigate Phil. We are definitely looking for stinky bleep, specifically in the bathroom.

We also know what to expect. When we are done resolving this issue, we should have a stinky bathroom.

But we still don’t have context.

Steps to Reproduce

So next, let’s add some information about how you came to discover that Dave’s bleep don’t stink. This can also be phrased as instructions for reproducing the bug. For example:

Steps to reproduce:1. Invite Dave to a Super Bowl party2. Allow Dave to eat a of nachos3. Allow Dave to use the basement guest bathroom4. Observe that the bathroom don’t stink

This is helpful because it allows the developer to run through the same steps as you did before and after they fix the bug. This means that they can verify that the bug is fixed before they ask you to take another look at it. It also means that you now have a set of test steps to walk through in the future.

As a side note, the first thing will do is repeat the steps I get. This is more than just an academic exercise, it’s a huge time saver.

A picture is worth a thousand words

Lastly, consider adding a screenshot or GIF to help illustrate the issue. For example, I could write about how Dave’s bleep don’t stink, but this video helps explain everything much more succinctly:

Supplemental content for odorless bleep. Issue #1337. Assigned to: Phil.

A few more things to keep in mind

Ensure that the report doesn’t need explanation

Unless you talk to the developer, your bug report is often the only way they will know to fix something. It goes without saying that we developers know how to write code, but not read minds. One helpful tip is to imagine that you printed out the bug report and then physically handed it to the person sitting next to you. If you feel like you would have to explain something as you made the handoff so that they can fully understand it, consider adding that “something else” to what you wrote.

If it can’t be reproduced, it might get ignored

Granted, bugs should be prevented as much as possible and should be fixed reasonably soon after discovery. But at the end of the day, developers also need to work on building software, not just fixing bugs. While we try to make an effort to understand a bug report that is not completely clear, if the steps to reproduces aren’t informative enough to observe the bug, the report will likely be flagged as “cannot reproduce” and/or “won’t fix.” This doesn’t mean we don’t like you, it just means that we eventually had to move on.

Don’t worry about over-explaining

Chances are, you will write a bug report immediately after you find the bug. That means that you have the whole situation fresh in your mind so “Dave’s bleep don’t stink” may seem pretty thorough. But keep in mind that the developer won’t know what you were doing or what you wanted to happen unless you tell them. Typically, writing an extra sentence or two will only cost you an extra 30 to 60 seconds, but could save developers hours of tracking down the same information. A handful of words can make the difference between a bug being fixed or being found again by another user.

Avoid links to other services (when possible)

I’ve had a few cases where testers wrote an otherwise fantastic bug report, but the video they captured that showed the bug was hosted somewhere that I couldn’t access. This sort of broken-link scenario is why I recommend embedding a picture or GIF right in the report. Most bug reporting tools support it and seeing everything in one place is helpful.

Developers are people too :)

We take pride in our work and want to make things better. We do our best to write good code, but we are human and therefore make mistakes. That’s not an excuse, we just need all the help we can get! 😃