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.
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.
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
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.
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
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.
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:
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.
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
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?
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
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:
- Login to the website using Safari or Chrome (works properly in Internet Explorer).
- Click on the cog in the top right corner, and select “Account Management” from the dropdown.
- Click on the plus symbol next to the “Add a team member” link.
- 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.
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
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.
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.
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.
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.