How to Write a Helpful Bug Report That Gets Your Issue Fixed

Why writing a detailed bug report is so important

That’s why it’s so important to write good bug reports from the get-go. Well written bug reports, prevent endless back-and-forth between two frustrated people and create a clear path forward. Beyond that, though, writing a helpful bug report is important for the following reasons:

You’re more likely to get your issue resolved

When you write a detailed bug report that has a number of details, steps, and explanations about what is going wrong, it makes it easier for the person viewing the report to understand what’s happening.

There’s less back and forth to determine what the issue is

Sometimes, it can be exciting to watch a mailbox and wait for something to arrive. That is not usually the case when it comes to support interactions.

It creates a more compelling case for fixing the issue

When you include a lot of detail in your first email, it creates a more compelling case and drive for the engineering team to resolve the problem.

  • Get milk and groceries
  • Put away the dishes
  • Do laundry
  • Call the phone company to figure out phone issues

Writing the perfect bug report

There’s so much information that you could potentially include when writing a bug report that sometimes it’s hard to know what to focus on. Here is a surefire formula to follow to make sure you include everything the fixer will need:

Quick Summary

At the top of every bug report, you should include a quick summary of the issue before diving more deeply into the information we cover below.

When the issue started and how often it occurs

One of the first questions that engineers ask after something has been reported is: how often does this happen, and do you know when it started?

Steps to reproduce the bug

Rather than writing out a whole paragraph of text, try to include numerical step-by-step instructions for how to reproduce the bug. For example:

  1. Login to the website using Safari or Chrome (works properly in Internet Explorer).
  2. Click on the cog in the top right corner, and select “Account Management” from the dropdown.
  3. Click on the plus symbol next to the “Add a team member” link.
  4. A spinning ball appears that never goes away. Upon refreshing the page and going through the process again, it continues.

Information about your environment

In keeping with the need for detailed information, providing as much information as possible about the browsers that you have used to recreate the issue is very important.

Steps that you have used to try to troubleshoot

If you’ve done any troubleshooting of your own to try to solve the issue, be sure to let the support or engineering team know that in your email. Did you try using other browsers, viewing the site in an incognito window, or signing into a test account? Head their next questions off at the pass by addressing those things directly.

Visual Documentation

Taking screenshots of what the bug looks like, any errors that are occurring in the browser’s developer tools, and of the steps along the way to reproduce the issue can be very helpful.

A template for bug reports

If you’re trying to teach your sister, support agents, CEO or customers to submit a detailed bug report, a template can be helpful. Here’s one we like to use that makes sure all the necessary information is included.


The more detailed that you can be in your message either to the support team or, if internal, to your engineering team, the better likelihood you’ll have with getting the issue resolved sooner rather than later.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store


Improve your #custserv & #custexp with Nicereply - a customer satisfaction survey software, including CSAT, NPS & CES 2.0