4 Things Worth Including in Bug Reports (and 5 Free Tools)
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.
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.
Expected Behavior
What were you expecting to happen?
Actual Behavior
What happened after your last step?
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)
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
- Mozilla has some great bug writing guidelines and more real-world examples
- Stripe 2018 Study: The Developer Coefficient
