Published: June 13, 2022 • 4 min read
You’re a person who opens bug reports for software engineering teams.
Perhaps your bug reports take a long time to resolve, and you’d like to help the programmers help you.
Maybe you’re frustrated with the extensive back-and-forth conversations around every report you open.
Bugs are part of software, and so is bug reporting. Reporting well is a necessary skill in an ever-growing number of job titles.
In this post, I’d like to explain how to write a perfect bug report.
What’s ‘perfect’? A perfect bug report allows the receiver to start meaningfully debugging, immediately.
Even on great teams, this isn’t always possible. However, you’ll find it’s commonplace on great teams.
Teams that are great at this tend to have either:
Here’s a markdown template I’ve used:
### Steps to reproduce ### Expected behavior Tell us what should happen ### Actual behavior Tell us what happens instead ### System configuration **Operating System**: **Browser**:
Let’s look at each piece of this report.
Steps to reproduce are vital. What are the givens, and what actions did you take?
Expected versus actual behavior comes next. The expected behavior is often skipped in bug reports, yet it’s crucial. If I’m not a consumer of the part of the application you frequent, I might not know what you expect to happen. Your expectation could be wrong, contain insider knowledge to your team, or expose other bugs that you’ve found ways to tolerate.
System configuration helps me start thinking about what the issue might be. If you’re experiencing zooming on an input, I expect that to be happening in Safari mobile. If you aren’t using Safari mobile, that’s useful information.
Attachments like images, video, and screen recordings are a major plus.
Here’s one of these forms filled out:
White Screen on Cart ### Steps to reproduce Given I am not logged in And I add a sweatshirt to my cart When I click on my cart icon in the navbar ### Expected behavior Then I see my cart with my sweatshirt ### Actual behavior Then I see a white screen (screenshot attached) ### System configuration **Operating System**: Windows 10 **Browser**: Chrome Version 102.0.500 Note: Seems to happen more during busy times.
Some bug reports have a field to indicate the severity of the bug. Does this affect one person (low severity), a team (medium), or all customers (high)? What is the importance of the bug?
I suggest you omit this field from the form. In my experience, the person creating the report usually doesn’t know the actual severity. How could they? Even if the site is down at your location, without communication it’s nearly impossible to know that that is true for all users.
What happens when the severity is wrong? When it’s overestimated, it can create a sky-is-falling reaction to bugs. When it’s underestimated, it can lead teams to de-prioritize important issues.
When an estimate is found to be inaccurate, we rarely update it, even when that mistake is widely understood. This leads people to tune out that data and sends mixed messages to observers.
To summarize, severity is easy to get wrong, and being wrong creates problems you didn’t have before.
A suggestion I’d offer to anyone opening a bug report: report what you see, not what you think.
A practice that hinders a bugfix is latching onto the wrong solution early in the process. The guidance “I think that Sidekiq email jobs are failing”, especially from a senior engineer to a junior engineer, sends one down a road. It may be the wrong road. “This customer didn’t receive this email” is better because that is not a theory.
If you’re a programmer who’s certain you know what’s going on, jump on a pair programming session with the bug fixer and confirm that you’re right from first principles.
“This feels like too much work!” you say. I get it. You didn’t earn an MBA or become an HR expert to write bug reports. It’s not part of your job description.
Unfortunately, software users find bugs that interrupt work. To fix them, I have to know some things. If I don’t know them up front, I’m going to ask dumb questions until I do. You’re saying a house is on fire. I need to know the street address.
And bad bug reports tend to resist fixing. Go to any bug reporting repository and look for the tickets that have been open for more than a few weeks. They’ll almost certainly be lacking one or all of the subheaders I described above. Avoid this morass by providing the minimum information.
This has been my attempt to demonstrate a perfect bug report. In summary:
Thanks for reading.
What are your thoughts on this? Let me know!
Join 100+ engineers who subscribe for advice, commentary, and technical deep-dives into the world of software.