How to Write a Bug Report That Doesn't Suck

Most of the time, engineers get poor bug reports that they cannot act upon.

Bad bug reports happen because "the average person" is usually not familiar with which information can help engineers fix the issue faster.

Here's a guide to reporting bugs that should be easy for anyone to understand.

Feel free to pass around the information below, especially when you get a bug report with little useful information.

Bug report template

1. Title
2. Steps to reproduce*
3. Resulting and expected behaviour
4. Screen recording or screenshot
5. System information*
6. User ID [If relevant]
7. Impact [If known]

*Certain screen recording tools include this information automatically

How to use this template

The most important thing to understand when reporting a bug is that the reader should be able to reproduce it on their computer only with the information provided. It is not always possible to reproduce the bug, but it's best to provide as much information as possible. 

Title

Briefly describe the issue, i.e. "Calculator: incorrect result of multiplication". Try to be concise, but specific here. For example, "Broken landing page" doesn't help the reader to understand whether the issue has already been reported and what exactly is wrong: Is it not accessible? Is the layout broken? Is it just a typo in one of the headlines? 

Steps to reproduce

Describe what actions you took before you encountered a bug. It can look something like this: 

1. Go to ExampleURL.com
2. Click button A
3. Select option B
4. Type "123"
5. Click Enter

It is best to try to reproduce the bug yourself, so that you can be sure that the steps provided will lead to a bug you are reporting. 

Resulting and expected behaviour

Specify what the outcome of your actions was compared to what you would expect the outcome to be. Examples: 

Thing X should happen. In reality thing Y happensI get an error "404. Page not found."

Screen recording or screenshot

There are many screen recording tools for you to choose from. Mac users can use QuickTime (see tutorial  here) or by pressing Shift-Command-5. On Windows 10 you can use the Xbox app (see tutorial  here). 

A faster way to make a screen recording for a bug report is to use a dedicated tool. Together with the video it automatically captures technical information that will help engineers fix the problem a lot quicker. This way you also don't need to worry about providing system information and typing up the steps to reproduce the bug - they will be documented automatically as well. To find a tool that suits you, you can go to Chrome Store, look for "screen recording" and pick the one that focuses on bugs.

In certain cases (i.e. typo on a landing page) there's no need to record a video - a screenshot is sufficient. To make one you can use the tools built into your operating system. See how how to make a screenshot on a Mac here, Windows - here. 

System information

1. Operating system (including version): Click here to find out this information.
2. Browser (including version): Click here to find out this information.
3. Device: Desktop / Tablet / Mobile
4. Time (including time zone): At least approximate time when you encountered a bug. 

User ID [If relevant]

If you or the reporter of the bug were logged in when the bug happened, provide the unique identifier of the account. It is usually either username or e-mail. 

Impact [If known]

In case you know how many people are affected by the bug or how much revenue is being lost because of the bug, definitely provide this information. It will help engineers and product managers assign the correct priority. 

Final thoughts

If you want your or your customer's issue to be resolved quickly, please try to file a good bug report - the one that makes it easy to reproduce the bug with the information provided. The more information engineers have, the faster they are able to implement a fix. 

It's not uncommon for product teams to receive like the ones below: 

• Nothing works
• Page doesn't load
• Everything crashes
• I don't see anything
• X is broken
• etc.

Please, avoid those at all costs. It will help both you and people, fixing the bug, to save time and frustration.