Never look down on the bug report.
With a compelling bug report, the bug report author wields tremendous influence over a software product, the team and their own reputation.
The top 3 most powerful elements of a bug report are…
- Bug title
- Steps to reproduce
Your bug title is your gateway to your entire team.
Everyone scans bug titles. The easier your bug title is to digest, the more likely your bug will be fixed.
If someone evaluating your bug needs to open your bug again and again because your title is too long and cryptic, you have wasted their time. Your bug title should describe at a high level what observation you are seeing and when you are seeing it.
There are exceptions to this general template, but following this formula leads to bug titles that save people time. Your bug is already a plea for someone’s time — why take up more time with a poorly worded bug title?
Developers scan bugs assigned to them by looking at the bug titles. Management scans bug titles to quickly determine which ones need to be fixed. Testers scan bug titles to look for duplicates and see which areas of the system are unstable.
With so many people looking at bug titles, it’s frequently baffling why more time isn’t spent crafting a concise and informative bug title.
Here are a few examples of clear bug titles…
- Client crashes when copying to clipboard while clipboard is busy
- Save dialog is blank after browsing to network drive
The 2 examples above exemplify a similar formula:
- observation WHEN something happens
- observation AFTER something happens
Coupled with a great bug title, a well-taken screenshot is the next key to an awesome bug report.
If the bug title and screenshot are really good, someone reading your bug might be able to skip the other details all together. It’s a great sign when with only the bug title and the screenshot, someone looking at the bug already understands the bug.
A screenshot with clear direction about what to look at and just enough explanatory text is priceless.
This is the best kind of bug, because it saves everyone time and communicates precisely what you’d like the team looking at.
If they want more information, they can read the rest of the bug, steps to reproduce, stack trace, etc.
If they want just enough information to understand what the bug is about and the impact of the bug (that’s what most people want to know!), then your bug title and a great screenshot are really all they need.
Steps to reproduce
Despite the awesomeness of the bug title and screenshot combination…
The steps to reproduce a bug are another important item and are generally most important to the developer looking to fix the bug.
Developers frequently complain about the steps to reproduce. Sometimes it’s the lack of detail in the bug. Frequently, it’s that the steps to reproduce the bug don’t really reproduce the bug.
Adding a great set of steps to reproduce the bug makes the bug easier to fix.
However, it’s generally much harder to get these steps just right than at first glance. The amount of detail to put in these steps is crucial.
You don’t want to waste your own time crafting super detailed steps to reproduce the bug.
You also don’t want to waste the time of someone who knows the bug area super well, since they’ll be trudging through mundane detail trying to extract the steps that really matter.
Finally, you don’t want to include too little detail so that someone new to the bug area can’t reproduce the bug. You need to find a balance.
Unfortunately, finding the right balance means that someone will be unhappy. The real question is how you keep the majority of people happy.
Two-phase approach to repro steps
A two-phase approach to repro steps is what I use to address this balance.
In the first phase, start with high-level steps for someone familiar with the area.
- Assume domain knowledge and familiarity with the bug area when writing these steps.
- Leave out the “click on this,” “enter this,” “launch this” steps.
- Think about how you would write the bug if you were reporting it to yourself.
- You probably wouldn’t care about all the mundane steps to accomplish an action.
- Instead of click File, then click Save, then enter your new filename, and finally click the Save button, something like “Save your document” is enough.
Once you’ve gotten this squared away, we move onto the second phase.
- Under each high-level step, add enough detail so that someone unfamiliar with the bug area can reproduce the bug.
- Make the high-level step more recognizable by highlighting it, underlining it, bolding it or putting asterisks in front of it.
- The idea is someone familiar with the bug area can scan the high-level steps, and someone unfamiliar with the bug area can dive into the more detailed steps.
So there you have it! The top 3 most powerful parts of an awesome bug report.
There are lots of other things to include that may help with the bug investigation: your environment, the build you’re using, observations, perceived customer impact, priority, severity, any debugging you’ve already done, etc.
Include anything you think that will help the team understand the bug, but make sure to use a concise, descriptive bug title, a great screenshot of the bug and two-level repro steps.