How to report bugs (if you want them fixed)

Intro

Most of the time engineers get poor bug reports that they cannot act upon. It happens because "an average person" is usually not familiar with what information can help engineers fix the issue faster.

We tried to create a guide that would be easy for anyone to understand. Feel free to send around the information below, especially when you get a bug report with little useful information.

Bug report template

• Title
• Steps to reproduce*
• Resulting and expected behaviour
• Screen recording or screenshot
• System information*
  • Operating system
  • Browser
  • Device
  • Time (including time zone)
• User ID [If relevant]
• Impact [If known]

*Some screen recording tools include this information automatically (see more below).

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 happens
• I 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 (i.e. Bird or BugReplay). 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.

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

Operating system (including version): Click here to find out this information.

Browser (including version): Click here to find out this information.

Device: Desktop / Tablet / Mobile

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.