Creating Better Bug Reports: Why it Matters and Where to Start.

While there’s no perfect way to create a bug report, there are potential pitfalls that can arise from approaching a ‘bug’ report in the wrong way. To help avoid these problems, we’ve assembled a short guide to get you on the right track towards creating more efficient issue reports and better end-products.

The term ‘bug’ as an error in computer operation was coined by Grace Hopper in 1946 when a problem with the Harvard Mark II computer was traced back to a moth trapped in a relay. Since then, we have called any odd quirk, error, defect, or oddity we see in software, a ‘bug’. However, this general term doesn’t always define the problem or suggest who the right person might be to fix it.

Why do we report issues?

To work out the best way to communicate ‘Bug’ (or more accurately, issue) reporting, we first need to look at the purpose behind them. On the surface, it is easy to just say that bug reports are pointing out things that are wrong. In reality, they solve multiple problems:

• Identifying something that is not working at all
• Identifying something that doesn’t match the specification or design
• Identifying something that is confusing
• Suggestions or ideas to make the software better

Determining which of these pertains to our issue report goes a long way in properly getting the best resolution.

So, how do we log a better issue report?

Issue reporting is an important part of software development and critical to refining a solid software product. Despite being so necessary, developers (and designers) sometimes bristle at receiving them. Why? Most of the time, it is all in the delivery.

The key to logging a good report is to put yourself in the shoes of the person reading it. There are a couple important questions that will be on the developers’ minds when they first read it, so let’s review those.

Type Matters

Bugs - something is broken that was working before
Feature - additional functionality added to the current site
Improvement - a suggestion to change the way something works

Developers want to fix things and make great code, so calling a suggestion a bug is basically an accusation that they failed. So, try to stick to observable facts. State your understanding of what was expected and what was unexpected. It can feel a little robotic, but it will help tap into that natural desire to fix things rather than putting your developer on the defensive, and you will be amazed at the results.

Less Helpful
When I click this fields nothing happens.

More Helpful
[Bug] In the admin user section, when editing Mary Johnson’s profile, I was expecting to be able to select her role from a pre-populated list of options. However, when I click in the professional role field, no options appear.

Context Matters

When an issue is being reported, it is tempting to only think of what is in front of you. You may want to send a picture of the problem, but oftentimes a photo is not enough on its own to convey where you are in the program. Include some context about where you are in the process or application so the developer can easily slide in to the right spot. It is critical to lay out what happens and what is expected, as well as give an example of how to recreate the same outcome. Oftentimes, issues exist because we are using software differently. Step-by-step instructions to reproduce the outcome will generally make the problem obvious and also lead to a solution much faster.

Less Helpful
The arrows aren’t working.

More Helpful
I went to the homepage and attempted to click the arrows and scroll through the photos. My steps were as follows:
• Navigated to the"Services" page
• Clicked on the logo to return home
• Scrolled down and attempted to click the arrows
• Upon clicking the arrows, I noticed the image didn't change.

All too often a developer revisits a bug a few weeks later and the person who originally posted the bug can’t remember how to reproduce it. If you don’t understand your own bug report a month later, it doesn’t have enough detail. If you write the report for future “you,” all parties will be better able to understand the problem as time passes.

Tone Matters too

Less Helpful
Submit button is STILL BROKEN! Can’t use.

More Helpful
[Bug] When I click the submit button, there is no obvious change. I expected to see a report submitted message.

The anatomy of an issue report.

So, what’s next? You’ve identified the type of issue you are experiencing and can describe it in an objective way that tells a story. Let’s look at what should be included in the report and how to piece it all together.

If possible, use an issue reporting tool. These tools integrate with your internet browser and automatically provide important system information as well as URLs, screen shots, and other data that helps identify the cause of the problem. They can also help you structure your report and not miss important information.

Whatever method you choose to relay the information, make sure to include the following:

Title - Choose a brief, clear title
This will help the development team easily sort and refer to issue reports. Make sure the title is a good summary with relevant detail but not the full description. Remember that these are often viewed in a list and keeping them clear and grouped is very hard if the title is unclear. Also, make sure you keep your report to only one issue. From your vantage point, they might look related, but they may not be internally.

Type - Identify if your issue is cosmetic, a feature request, or an error
Identifying the category of the issue report can actually go a long way for developers. Is it an error, do we have a suggestion, or is it just something visual? Is something actually broken or is it just the wrong color? Denoting your reports in this way speeds up the process of routing the report to the right person.

Description - What was expected? What happened?
This is where all that context will come in to play. Fully explain what action was expected that did not happen. What did you think should happen? Is this different than designed (incorrectly programmed) or different than you expected (potential design discussion). If this is a request/change, be very specific as to what is requested or indicate that it needs designer input with what you have in mind. Images can also help tell the story. Annotated screenshots are a great way to point to the exact place you are encountering the issue.

Bonus: Notate as much additional information as you can
If you want to go above and beyond, provide any extra info and technical details you might have. Was there an error in the console? Does this only happen after other specific actions? Were you able to make it happen more than once? All this helps get to the problem faster. Is there a useful screen capture you can provide? If so, please attach it to the issue report and leave a comment about the file if there is relevant information to provide. The less the developer has to hunt for, the faster the problem can be identified. In most cases, fixes are 95% searching and 5% changing.

There might not be a perfect way to assemble bug reports, but there are things that can help. Whether you are reporting newly discovered issues, suggestions, changes, or bugs, attention to detail is important. With any project, all members involved are on the same team, working for the same outcome. If you follow these proposed guidelines and remember the perspective of those who are fixing bugs, the result will be better internal communication, more efficient processes, and of course an even better end-product.