Write a great bug report
A great bug report can be as short as a tweet. When written well, it can be quickly addressed—and will earn you the love of your dev team.
When software isn’t working right, it’s more than just an inconvenience. It can be frustrating: a waste of precious time, or something that you know worked before dozens of times, but now inexplicably not. It can be aggravating: standing in the way of completing a task or making a deadline. And it can be fear inducing: what if my data is lost? What if it’s a sign of something bigger at play? What if I did something wrong?
Most of the time, it’s not the latter. But there can be a bewildering variety of reasons why a bug is happening—from network connections to clashing sub-system updates, conflicting business rules to edge cases that weren’t considered. There’s probably a dozen layers at which a bug might be hiding.
To help your development team figure why the bug is happening and how to fix it, you’ll need to provide some specific information. Here’s a five-point bug report template that gives developers exactly what they need:
- When I (steps to trigger the bug),
- I see/I get (describe the error).
- I was expecting (describe the intent, if it’s not obvious).
- I’m using (browser/version, operating system/version).
- Screenshots!
What’s the trigger?
Describe the steps leading up to the bug. Where were you? What were you doing? What interactions did you have? Your description should be short and to the point. Make sure the bug is repeatable using the same steps.
What happened?
If you see an error screen, include that, ideally in a screenshot (see below). Otherwise, describe the error.
What did you expect?
If it’s not evident from the above, adding your expectation can be very helpful. This is especially true for software that embodies complex business rules, like importing or exporting.
What were you using?
If you’re using a web browser, you’ll need to report the brand (Chrome, Safari, Internet Explorer) and version. If it’s desktop software, include its version number. You’ll need to describe your operating system (Android, Windows, MacOS) and version, too.
Screenshots
A picture paints a thousand words! Sending a screenshot along with your report brings even greater clarity. If it’s a web application, include the entire window, and not just the problem spot. Simple markup tools like highlights, circles, or arrows can help, too—but keep it simple. Something is better than nothing.
A great bug report can be as short as a tweet! Here’s one I sent recently that uses this template:
When I @mention a teammate’s name in a channel, I see only parts of the name, broken up, and can’t send the message. If I use the @lookup icon, it keeps adding in names. I’m using version 2.8.0 on MacOS 10.13.3. Here’s a screenshot!
Use this format, and your bug reports will be concise, actionable, and loved by your dev team.