Writing a Bug Report 🐛

Why? #

A report needs to be consistent and written in a manner that allows any team member to verify if the bug exists. From the engineers to the designers to the product owners, everyone should be able to reproduce a known bug.

The ability for all team members to understand what is happening and why is an excellent exercise in knowledge sharing and developing a bug database.

Consistent Reports #

Below is the format I follow:

Component Affected - Brief Description of the bug

*Environment Used*
Operating System (example: Windows, OSX, Ubuntu)
Unique Hardware (example: bug occurs on low dpi monitors)

*Affects Browsers*
List of browsers and their versioning numbers (Chrome, Safari)

*Steps to Reproduce Bug*
1) Steps should be written in a manner that anyone in the
company can reproduce the bug.
2) Be very thorough in your directions. If people can't
easily reproduce the bug, the ticket will may be closed with
a status of "can't reproduce."

*Expected Behavior*
What you expected the application to do.

*What the Behavior Currently is*
What the application currently is doing, the bug.

*Additional Info*
Included any screenshots, gifs, movies, HAR files, notes,
or any other resources that can assist in all levels of triage.

What is Additional Info? #

Additional info provides context that can help everyone understand the root cause of the bug and prioritize the severity.

While GIFs, screenshots, and notes are relatively straight forward, some people may not know about HAR files.

HAR files can be thought of as the flight recorders of browsers. Every event will be saved into a JSON file. Depending on the bug being created these can be immensely useful or not not worth the effort to capture at all.

An example when a HAR file can be useful?

Take an application that requires complex user interactions to display a data visualization. The ability to filter data and redisplay it requires user finesse but what if there are certain interactions that cause the application to break? A HAR file can tell us what events caused what HTTP responses (or requests).

How to create GIFs? #

I have no affiliation with Gifox, but I am a major user of the software. When starting at a new company it's one of the first things I will buy for my work machine. It's only available on OSX and, at the moment, costs $15. I highly recommend it:


A free alternative if you are on Windows is ScreenToGif. While I have not personally used it many of my coworkers have and spoke highly of it:


The Hustle

Since you've made it this far, sharing this article on your favorite social media network would be highly appreciated 💖! For feedback or if you have any questions, please ping me on Twitter.