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

Well written bug reports, prevent endless back-and-forth between two frustrated people and create a clear path forward.

Bug reports are a universal language. Unfortunately, not everyone is fluent. Whether you’re a customer trying to get help or an agent working in technical support, it’s critical to write a great bug report to get the issue fixed quickly. We probably all have seen a “bug report” like this:

Something is wrong with your product. It doesn’t do what it’s supposed to do. Fix it.

That’s certainly cathartic for the person writing the message to express — they get out a little bit of their frustration and anger — but it doesn’t help the person on the receiving end know anything beyond the fact that, literally, something is wrong. They’ll have a lot more questions to ask before they can start to fix whatever is wrong, which is frustrating for both customer and the fixer.

Why writing a detailed bug report is so important

You’re more likely to get your issue resolved

For example, if you were to give someone driving direction and say “Turn left after you’ve been driving for a little while,” versus “Turn left when you see ‘Arbor St’, it’s 2 miles down the road, and there’s a blue house on the corner,” the likelihood of someone getting where you want them to go is much higher with the latter than with the former. Now, imagine that as a bug report.

When you say “my username and password isn’t working,” it could be myriad issues that are occurring to cause the problem. It could be anything from a pop-up blocker to something not firing properly on the website, to mistyped usernames and credentials.

Without much information to go on, the person trying to help may look around aimlessly prior to emailing back to ask for more detail. Save both of you the time it takes for the back and forth, and you’ll get a resolution much more quickly.

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

No one wants to be sitting at their computer, watching Gmail like a hawk and waiting for a response to their support inquiry to come in. But when you’re having an issue that merits a bug report, sometimes it can feel like life or death and you need to have the resolution as soon as possible.

To avoid those hours of staring at your screen waiting for an email, include as much detail as possible. You’ll reduce misunderstanding, cut down on the back and forth, and give the clearest amount of context so that the support agent can spend their time figuring out the cause of the problem rather than trying to figure out what the problem even is.

It creates a more compelling case for fixing the issue

Without all of the information needed to debug an issue, it can take a back seat to any other bugs with obvious resolutions. Anyone looking to create some kind of prioritization would rather start with the clear-cut, straight forward issues and work their way up to ones that need deeper looking into or more work.

For example, if you were to make a list of tasks to do around the house that looked like this:

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

You would probably prioritize calling the phone company last. Why? Because it’s going to take time, you aren’t quite sure what the issue is, and you aren’t even sure if you’ll be able to get a resolution by just calling the phone company, or if it might take multiple calls, or even speaking with another company altogether to get a resolution.

The same goes for the engineers and support people working on issues: just like you, they want to handle the things that will be quick and easy prior to sinking their teeth into something meaty that could take them awhile.

When you provide detailed information about the problem, as well as what you did to get to the issue, it makes things clearer to diagnose and understand. It allows the person working on the issue to understand how much time it’s going to take, also, and prioritize it into their daily work.

So, how do you write a helpful bug report? There are a few things that you can include that will make a world of difference to the support person or engineer reading the report. Let’s take a look:

Writing the perfect bug report

Quick Summary

For example, saying something like “X behavior is happening, but I would expect Y behavior to be happening instead.” This way, the engineer or customer support agent reading the bug report has a more solid handle on what is occurring, before diving into a bunch of information that might not make sense without context.

Including the expected outcome, versus what is actually happening is an excellent way to loop others into what the past behavior of this particular feature has looked like as well.

When the issue started and how often it occurs

By including that information in your first email, you save yourself at least one email back and forth. This is as straightforward as saying something like “This happens about every fifth time that I refresh the browser, and it started happening yesterday afternoon.”

Steps to reproduce the bug

  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

For example, if you have tried both Chrome and Safari and they are having the same problems, include that in the email along with the version information for both. Also mention any browsers that you haven’t had the chance to try, as that will give the person testing a place to start with their search.

Support Details is a really helpful tool for support agents and customers alike. Head to the site and it will collect all the details about your system set-up and even let you email them to the agent you’re working with. If you support customers, it’s an easy way to collect all the information you need.

Other useful things to include, beyond what browser you are using, is information about your operating system, geographic location, internet service provider and even the type of computer you are using. Some things can be caused by outages outside of the company’s control, and having that information can help rule such issues out.

Steps that you have used to try to troubleshoot

Visual Documentation

Just like some people do better by looking at videos than reading the documentation, providing a visual representation of the issue at hand can be similarly helpful.

A template for bug reports


Provide as much detail as you can, both visually and in written form, as well as clear steps to be able to reproduce the problem. If you’ve done work on your own to try to fix the issue, convey that as well — it’ll save the team some time.

It may take extra time to sit down and write in extreme detail, but the long-term advantage is that it will take less for the issue itself to be resolved. The more organized and detailed you can get with your bug reports, the better.



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