How to Write a Bug Report so that an Engineer Actually Fixes the Bug

If you want an engineer to act on a bug report, it needs to be easy to understand. Most importantly, the recipient needs to know how to reproduce the issue.

The worst bug reports look like this:

Weather query doesn't work

That’s it, no context. It’s impossible to understand what’s going on.

The best bug reports clearly state:

  • How reproduce the issue (“To Reproduce”)
  • The expected user experience (“Expected Behavior”)
  • What actually happened (“Actual Behavior”)

Take this fictional example about the Google Assistant and asking for the weather on the app’s main page (“chat UI”).

Title: Weather forecast ignores user location

To reproduce:
1. Open the app
2. Sign in to your account (or already be signed in)
3. Ensure that "use location" setting is turned ON
4. Type "weather tomorrow" in the query box
5. Tap "Send"

Expected behavior:
Chat UI shows weather forecast at user's location

Actual behavior:
Chat UI shows weather forecast in Santa Cruz, CA *regardless of user location*

This report is easy to understand and as a high chance of being acted on by a developer. It has step by step instructions on how to reproduce the issue. Receiving a report like this won’t be seen as a complaint–rather, this is a legitimate bug that needs to be fixed.

Bonus points: To encourage reporters to provide structured information, create a default template for your bug reports.

This entry was posted in Software and tagged , , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s