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.
Pingback: 100 Things I’ve Learned as a Software Engineer at Google | Sheldon's Software