How to Write Bug Reports that Make Developers Happy

Songtham Tung
Nov 12 · 6 min read
Photo by Tyler Nix on Unsplash

Bugs are everywhere. This statement holds true whether in the wild or on the world wide web. The latter is what this article focuses on, which refers to errors or unexpected results in a computer system.

In a previous blog, I wrote about What is QA Testing?. This article builds on top of that, with a focus on how to write bug reports for technical issues. Whether you are a user, tester, or developer, I hope that you will find this useful and applicable for your everyday life.


If You See Something, Say Something.

“More Code, More Bugs. “ — Software Engineering Proverb

I’m going to take a stance and say that there is no such thing as bug free software. It’s a widely held belief that the more code there is, the more bugs there are. And according to Murphy’s law — anything that can go wrong, will go wrong.

The key point here is that when you encounter a bug, do the community a favor and immediately report it. Can’t create a story on Medium? Report it. Can’t watch videos on Youtube? Report it. Uber can’t find your pickup location? Report it. Chances are, others are having the same issue as you. So help them, help you. However, the quality of your report makes all the difference. The more detailed the report, the better. But what exactly makes a good bug report and how can I write one myself?

The Perfect Bug Report

When compiling this list, I reflected upon my experience working with various tech companies. I’ve seen bug reports that was clear on the first look and others that needlessly bounced back and forth for several days, ultimately wasting time, money and energy.

The perfect bug report, in my humble opinion, is one that developers can understand and reproduce immediately — no questions asked.

Your goal should be to create bug reports that can be easily understood and replicated on the first look. Regardless of the system used (email, Slack, JIRA, GitHub, etc), good bug reports share the following qualities:

1. What is the issue?

This is the subject line in an email and the title of an issue in a bug tracking system. If you’re struggling to write a good opener, consider asking yourself: in one sentence, what happened?

Example of a Bug Ticket Title in JIRA

For example, if you are trying to subscribe to an email newsletter and the submit button is not working, consider writing an email to customer support or filing a new bug ticket with the subject as Email Newsletter Submit Button Not Working.

The bug is clearly described and the severity of the issue can be gauged just by reading the title.

2. What browser / device / version are you using?

This is one of the most common first reply in any bug reports. And do you know what’s the first thing that developers say behind the scenes?

It works on my machine ¯\_(ツ)_/¯

Avoid the unnecessary dialogue by always including the browser, device, and/or version that you were using in the body of your report.

For example, were you using an app or browser when you encountered the bug? If app, were you using iOS or Android? If browser, which one? In each scenario, what version were you using? Provide this information upfront and it’ll make the lives of the tech team easier.

3. What steps did you take?

This question is perhaps the second most common reply in any bug reports. To put it in another way, one might ask “How did you find the bug?”. Communicating the exact steps that you took is essential because the developer needs to be able to reproduce the bug in order to fix it. As obvious as it may seem to you, it may not be as obvious to them.

Writing the steps to reproduce a bug is basically writing a set of instructions or manual for the tech team to follow. Keep in mind that the language used is straightforward, logical, and concise. In other words, it should contain 100% facts and 0% opinion.

For example, writing the steps to reproduce for the email newsletter bug might look something like this:

1. Navigate to www.example.com
2. Scroll down to bottom of page
3. Enter Email
4. Submit
5. Error

Even though this is a simple example, it demonstrates a clear set of instructions for anyone to follow. This leaves no room for interpretation.

4. Include evidence (images, videos, error logs)

I’ve seen countless attempts where well-intended individuals would write really good bug reports, only to drop the ball on providing good evidence. Good evidence is something that shows exactly what’s going on. Bad evidence does not.

For example, I’ve seen many screenshots that only tells a fraction of the story.

Photo by Patrick Brinksma on Unsplash

To illustrate this point, let’s use a generic eye picture. Can you tell what race this person is? Are they male or female? Young or old? Happy or sad?

I can’t.

And you probably can’t either, unless if you’re the person who took the picture. When including evidence in your bug report, always show it in its entirety. If it’s a website, be sure to include the URL and entire page. Remember who the bug report is for — developers. Developers don’t know everything, even if they were the ones who built the system. They literally need to see the bigger picture to better understand how to fix it.

“A [great] picture is worth a thousand words.” — English Proverb

Cropped pictures doesn’t do it justice and will typically result in the tech team pushing back and asking for clarifications. The same applies to videos and error logs. Videos are great at showing the series of steps that you took and if you happen to see any error logs, be sure to include it in the report.

It’s a Buggy Bug World Out There

As mentioned in the beginning of this article, bugs are common and they are everywhere. Some are minor issues and others are catastrophic. Regardless of the size or magnitude of them, it’s our duty as good citizens to report bugs to the proper channel when we encounter them. As funny as it may seem, by doing this, you are making the world a better place — or at least more bug free.

To recap on the main lessons from this article, the best bug reports are ones that developers can easily understand and reproduce immediately.

When reporting bugs, follow this guideline:

Thanks for reading — and be sure to follow me here on Medium for more interesting software engineering articles.

Songtham Tung

Written by

Technical Product Director @ Geddit | B2B SaaS | SF ✈️ BKK

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade