4 Things Worth Including in Bug Reports (and 5 Free Tools)

A green iridescent beetle
Photo by Stephen Hocking on Unsplash

Reporting bugs should be like writing a recipe. You should tell you what you’re cooking, a list of ingredients you need, easy to follow steps, and what you can expect at the end.

Maybe it’s troubleshooting over Slack or MS Teams, perhaps it’s writing up a formal bug report in JIRA — maybe you’re just in the break-room and want to share a problem you ran into.

Stripe conducted a study in 2018 reporting that ~$300 billion Global GDP was lost from developer inefficiency annually. Regardless of your role, the less time you have to spend explaining an issue to someone, the more time everyone has to tackle the problem.

4 Things I include in my bug reports:

  • Title
  • Steps to Reproduce
  • Actual Behavior
  • Expected Behavior

Title

I like my titles to be short and informative. Describe what’s happening in a way that anyone can read and get up to speed at a glance.

Here are some initial/original examples for each of these, what’s wrong or missing, and how to improve upon them.

table that describes original titles, what’s wrong, and improved titles
table that describes original titles, what’s wrong, and improved titles

Steps to Reproduce

Without steps, it’s tough to guide someone to the problem. Steps should take someone from the first click, through your actions, and right up to the actual behavior.

table that describes original steps, what’s wrong, and improved steps
table that describes original steps, what’s wrong, and improved steps

Expected Behavior

What were you expecting to happen?

table that describes original expected behavior, what’s wrong, and improved expected behavior
table that describes original expected behavior, what’s wrong, and improved expected behavior

Actual Behavior

What happened after your last step?

table that describes original actual behavior, what’s wrong, and improved actual behavior
table that describes original actual behavior, what’s wrong, and improved actual behavior

Bring it all together

Now let’s combine all the parts:

Title: When creating a Gmail account, error is displayed

Steps to Reproduce
1. Open a Browser
2. Navigate to Gmail.com
3. In the top right, click “Create an account”

Expected Behavior: user is directed to the Create an account screen
Actual Behavior: user receives a 504 error (screenshot attached)

Google 504 error screenshot
Google 504 error screenshot

Additional Info and 5 Free Tools:

Not every bug fits nicely in a template. Depending on the issue, sometimes it’s helpful to add other info.

  • Screenshots: Windows and MacOS have build in screen shot functionality
  • Annotations I personally use Greenshot; I find the annotations, arrows, and drop-in text helpful in pointing out. Awesome Screenshots is a great add-on for browsers.
  • Template of the Bug Report: instead of typing out “Title, Steps to Reproduce, Actual Behavior, Expected behavior”, I use a text expander (BeefText) to quickly spit out the template, then fill in details.
  • Attachments: did you upload a file? Share it.
  • Environment: does it work on FireFox but not Chrome? Did you only test it on Safari? Include that.
  • Other helpful info: does it only work if you input a certain string of text? Is there a work-around for the bug? Even if you’re not sure about “why”, it can be helpful during investigation.

Additional resources

A guy with keyboard and dog curled up in the corner.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store