Sep 16, 2019

How to report bugs
(if you want them fixed)

especially if you are not technical

Intro

If you work in a software company, you probably encounter bugs regularly. Some are reported by users, some - you find yourself. Either way, you should always let your engineering team know about those issues to have them fixed as soon as possible.

Unfortunately though, most of the time engineers get poor bug reports that they cannot act upon, which results in either the bug not getting fixed at all or additional communication between departments needed, that can be easily avoided with a good bug report.

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 (like 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.


    Follow the Bird
    Subscribe to our newsletter that's not very periodic
    Made on
    Tilda