Ever receive a bug report that looks something like this?
Title: European sales office descriptions and pins not displaying.
Description: https://www.clientsite.com/locations?region=eu
Show European Sales Offices on clientsite.com NA as when viewing via other regions.
Yes, it is confusing. Just looking at the title, you wouldn’t know what “pins” are until you find out you’re working with a map. You wouldn’t know what “European Sales Offices” look like if they’re not even showing up. You wouldn’t even know what “NA” is in this description, it looks like a typo. Lastly, you won’t know what all of this is talking about if you’re new to the project.
If you have seen this kind of bug report, you’re not alone.
A lot of situations can cause “stubs” – bug reports with barely any information. Project managers could be in a meeting, and forget to fill in the details later. Or the developers assumed to be in charge of fixing the bug are in the same meeting, and adding details feels redundant. It could be that project knowledge is thought to be known by all, so no additional details are needed.
Stubs aren’t necessarily a problem. The problem is when the assumptions made fall apart, and stubs remain stubs.
The unwanted side-effects
Tickets like these affect a company on all levels.
To new developers, a vague bug report might cause them to wander off aimlessly. They’ll be unproductive until someone provides some context on the issue, gives insight into existing implementation, and draws the line between what’s a good and bad approach. New developers often find it hard to seek out help, which can make this even worse.
To veteran developers, a vague bug report adds overhead to what might already be tedious work. This overhead could come in the form of finding people, setting up meetings, pair programming, anything that would require them to stop what they’re doing for something else that’s potentially unrelated. What could have been a 15-minute fix can easily become a week-long exercise.
To clients, a vague bug report can lead to signs of unproductiveness and unstructuredness. This manifests in the form of excessive back-and-forth conversations, multiple meetings, slow pace of development, and showing no signs of progress. Clients might question whether they chose the right vendor for the job.
Every moment wasted doing unnecessary work is burning margins. Especially troublesome is if that unnecessary work could have been avoided in the first place.
Solving the root of the problem
Writing bug reports isn’t that hard. A good bug report only contains five major components:
- Title
- Summary
- Steps to reproduce
- Expectations
- Additional details
You can either remember them (five things isn’t that hard to remember, is it?), or have your issue tracker remind you by way of a placeholder text or required fields.
1. Start with a good title
Capture the essence of the issue in one sentence. For the stub example above, the title could be rewritten to mention the involvement of a map and the region filter in addition to the pins and description:
Title:
Locations map does not render Sales Offices pins and description when filtering locations to show only EU regions
2. Add a summary
A summary should be kept short, around three-four sentences. It should expand on the title and, at the same time, add additional details that couldn’t be conveyed by the title alone. Fun fact, there’s actually one side-effect of the bug: the map centers in the wrong area of the world:
Summary:
On the locations page, filtering the map to only show European region locations does not render the European Sales Offices pins and descriptions. Additionally, the map renders the middle of the Pacific Ocean.
3. Outline the steps to reproduce
This is the heart of a good bug report. Start from a good known location in the app and drill down from there. Verbosely list down each step until the issue is reproduced. The example stub never had steps, but it could have been outlined like this:
Steps to reproduce:
1. Go to the homepage (https://www.clientsite.com/).
2. On the menu, navigate to Locations.
3. View the map.
4. Change the region filter to Europe and click Apply.
5. View the map.
4. Define the expectations
A bug report is useless without defining what’s correct from what’s wrong. A developer wouldn’t know what to look for, and a QA wouldn’t know what to test against. Point out specific steps where differences occur. In the example stub, the bug happens after updating the region filter, at step 5.
Expected:
At step 5, the map center in the Europe area and show pins for each sales locationActual:
At step 5, the map shows the middle of the Pacific Ocean.
5. Add additional details
This includes OS and browser information, installed extensions, etc. It’s not uncommon for a bug to manifest only in certain hardware and software setups. For instance, the presence of an content-blocker could easily break the usage of analytics APIs. The example stub bug report never mentioned additional details, but here’s an example:
Additional details:
OS and version: MacOS 10.14.6
Browser and version: Firefox 70
Browser extensions: Adblock Plus
Altogether, the bug report looks like this:
Title:
Locations map does not render Sales Offices pins and description when filtering locations to show only EU regionsSummary:
On the locations page, filtering the map to only show European locations does not render the European Sales Offices. Instead, the map displays the middle of the Pacific Ocean.Steps to reproduce:
1.Go to the homepage (https://www.clientsite.com/).
2.On the menu, navigate to Locations.
3.View the map.
4.Change the region filter to Europe and click Apply.
5.View the map.Expected:
At step 5, the map on the page should show the European region with pins marking the location of each sales office in the region.Actual:
At step 5, the map shows the middle of the Pacific Ocean.Additional details:
OS and version: MacOS 10.14.6
Browser and version: Firefox 70
Browser extensions: Adblock Plus
Going by this report alone, you can already see one possible direction where this bug is headed. For example, you’ll potentially be working with Google Maps. Seeing that an Adblocker is in place, a blocked Google Analytics could have thrown a script error causing the map to break. The map centering in the Pacific Ocean is a sign that the map might not have received the location data, because aside from Adblock Plus, Firefox comes with a content-blocker enabled by default.
Just by adding a bit more detail, potential causes and paths to fixes can already be named.
The benefits of writing this way
Writing bug reports this way promotes consistency and predictability. Having a predictable bug report format removes guesswork and the extra number of round-trips caused by it. You don’t need to find people to explain the bug in more detail; the information in the bug report is enough to get anyone started.
And this is not an isolated practice. In fact, you can see this in a lot of open-source projects. Mozilla has a page specifically for bug report writing guidelines. Most open-source projects also provide “issue templates,” allowing open-source maintainers to set expectations for bug reporters on how they should write their bug reports and what is expected of them.
We use JIRA as our issue tracker. One neat feature is the Development Panel. It gathers all work related to the issue into one panel so everything is a link away. From pull requests, branches, even down to individual commits, JIRA makes it easy to find all the work for any given issue. This perfectly complements the practice of putting all the needed information in an issue ticket by making it a hub for everything you need. Neat, huh?
Summary
To write a good bug report, the minimum you need are these five pieces of information:
- A good title
- Clear summary
- A verbose set of steps to reproduce
- Expected and actual outcome
- Any additional details
And that’s it! It’s not rocket science, not even 7 items to remember. And again, stubs aren’t the problem. Writing details later isn’t a problem. But do remember to add details to your bug reports sooner rather than later. And write bug reports in a consistent manner. As seen above, a little detail can go a long way.
For boutique companies, where responsibilities and roles get shuffled around, it’s easy to lose context. Writing bug reports in a prescribed fashion gets everyone up to speed. Conversation may be king, but having details up front is much more efficient.
Learn more
- How We Crush Bugs and Save Time with Automation: Where, why, and when to use automated QA testing, by Carl Swanson
- Contact GovWebworks with any questions
