When you find bugs in your home, you call an exterminator. When you find bugs in your software, you call a developer.
It may seem like these two professions are massively dissimilar - one is armed with bug spray and the other a keyboard - however you’ll notice parallels in their approach. The exterminator will request a description of the bugs you saw, where you saw them, and ask some questions that help them assess how they may have gotten there in the first place. The developer will want all the same things - a description of the bug, where it happened, and further information to help them assess how it happened. Our handy guide below walks you through how to answer developers’ questions before they even need to ask them.
But First: Why is this Important?
Developers can’t fix bugs based on information they don’t have or understand, and it is highly unlikely they can fix bugs they can’t replicate. Providing thorough, clear information helps the developer to identify the issue and its possible causes. The faster they can find and replicate your bug, the faster they can provide a solution.
Also…What IS a Bug, Exactly?
Bugs come in many shapes and levels of possible destruction. Some bugs are simply annoying like fruit flies - or aesthetic user interface elements that don’t display properly. Others, in the vein of ants or mosquitoes, can cause some pain, like buttons that don’t react in the way they were intended. On the far end of the scale you have the killer bees - bugs such as an inability to login that render software useless. In short, a software bug is any perceived issue or unexpected behavior experienced in the software’s functionality or design, no matter the size. However there is one thing that all bugs have in common - they all deserve a well-written bug report!
Tip 1: Keep Your Title Short and to the Point
The title should be comprehensible at a glance. A helpful title will include the fault itself, where it happened, and oftentimes what led to the fault.
Unhelpful Bug Title: The “continue” button isn’t working
Why isn’t this helpful? The developer doesn’t know where the “continue” button is - there are dozens of them across the site. Additionally, what is meant by “button isn’t working”? Is it going to the wrong page? No page at all? Is it functionally working but the drop shadow effect that is supposed to appear when hovering the mouse is not appearing?
Helpful Bug Title: Clicking the “continue” button at the bottom of the Product XYZ Details page leads to a 404 error”
With this title we now know what the issue is (going to a 404 page), where to look (the bottom of the Product XYZ Details page), and that the fault involved actually clicking the button.
Tip 2: Provide a Thorough Summary
The example above offers a bug that is easily described with the title alone. But what happens when the bug is more complicated than that? Use words to paint the picture of the bug - and what happened leading up to it. No need to include “I had just sat down at my computer with my coffee…” but do include details such as when the error occurred, where it occurred, any error messages received, and anything else the developer may find relevant to the instance.
Unhelpful Summary: I tried logging in several times but it wasn’t working.
This summary raises more questions than it answers. Do you already have an account? Did you try the same thing several times or different things?
Helpful Summary: “This morning I tried logging into my existing account using username and password credentials I have had for a while. I used the login popup from the upper right hand corner of the home page. Clicking the “Login” button brought me to a page with this error message: “Incorrect username or password.” I used the “Forgot Password” link below the login, but even after resetting my password I still receive the same error message.
This summary includes when the error occurred (this morning), where (the upper right corner login link on the home page), the verbatim error message, and details on remedies the user tried that ultimately failed.
Tip 3: Share Your Perspective on the Difference between Expectation and Reality
Understanding what makes a bug “wrong” is made easier when we define “right”.
It could be essential to solving the bug to include what you expect to happen when you attempt a specific action and what actually happens when you do that action.
Any time you can, provide what you expected to happen (even if it seems to be implied) and what happened instead, presumably, the reason you are submitting the bug report.
Unhelpful Example: When I tried sorting the list I expected it to be in the right order but it wasn’t.
This sentence doesn’t explain what the “right” order would be, nor does it illustrate what is “wrong”. The developer will not be able to confirm they have replicated the problem on their end.
Helpful Example: When I tried to sort the list in ascending order, I expected it to be put into numerical order (1, 2, 3, 13, 15, 22) but instead it sorted like this (1, 13, 15, 2, 22, 3).
This statement makes a very clear distinction between what was expected to occur and what actually occurred - the developer would have a much easier time of confirming if the error can be replicated on their end with this statement.
Tip 4: List the Steps to Reproduce the Bug
The summary provides a narrative of the issue, but a step-by-step guide to reproduce the error may be needed to clarify exactly how the bug can be triggered. For any bugs that may require more precision in guiding the developer to the issue, offer a list of precise and easy-to-follow steps.
Unhelpful Example:
Step 1: Enter a number in the form
Step 2: Scroll, get error
Where in what form are we entering a number? What specifically is meant by scrolling in this instance? Try instead:
Helpful Example:
Step 1: Open the “Product Quantity Tracking” form.
Step 2: Go to the “Quantity” field. Enter any number.
Step 3: Use the scroll feature on either a mouse or a trackpad. The number in the field will either increase or decrease based on which way you scroll. This is the bug; once a number is typed in it should not be able to be changed by scrolling.
Note: Click anywhere outside of the “Quantity” field. You will be able to scroll up and down the page without altering the number in the field.
With this step by step guide we now know exactly where to go and what to do as well as when we should expect to see the issue.
Tip 5: Set the Scene - Include the Environment
If you feel your hands are starting to cramp from all the typing you’ve done on your report, don’t worry - you’re almost there! The final written element you should include is information on the environment in which this bug appeared. Let the developer know what device you were using (computer, tablet, or mobile phone), its operating system (e.g. iOS 11.2.1, macOS 13.1, Windows 11), and the browser you were using (e.g. Chrome, Safari).
Tip 6: Include the Source URL
If applicable, include the source URL for the page on which the error occurred. Copy and paste the entire URL address into the report so the developer can go straight to the page where the bug occurred.
Tip 7: Provide Supporting Documentation and Evidence
They say a picture is worth a thousand words - similarly, screenshots can be a big help in identifying and understanding how a bug is presenting itself. When reporting a web-based error, include the URL in the screenshot. For all screenshots, include a markup that circles, points to, or annotates anything the developer’s attention should be drawn to. The screenshot should pair well with the bug report - point out any specific issues described in the report using the same language you used before.
Tip 8: Review Your Bug Report
We’re in the home stretch! Shift your perspective and imagine you are seeing this bug report for the first time. Read it through checking for clarity and thoroughness. Does it look like everything you would need to recreate and identify the bug is there? Does the language in the report align with any supporting documentation included? If so, send it!
Tip 9: Expect Questions and Provide Thorough Answers
There is a decent chance the development team may still have questions - this does not mean that your bug report wasn’t good enough. Additional information may be needed for them to fully comprehend the circumstances under which the bug occurred. Respond to questions with the same attention to detail, clarity, and thoroughness with which you assembled your initial bug report.
Tip 10: Know that Some Bugs May Be Labeled as Not Worth Fixing
Some bugs are more threatening than others. Just like an exterminator will prioritize handling a termite infestation over an errant cockroach, developers will focus on tackling the more dangerous software bugs first. It is also entirely possible that some bugs may be innocent or contained enough to allow them to exist - developers’ time is limited and focusing on new features may be more valuable than solving minor bugs.
Bonus: Bug Reporting Tools
There is a swarm of tools that exist to make writing bug reports and capturing detailed information easier. We have experimented with many of them and found a few that we don’t just like, but love. While none of these tools provide 100% coverage of the elements of a good bug report, they save a ton of time for both the reporter and developer by capturing both video and technical information. Below you will find a couple of our favorites; they have become staples in our daily work and were created by some fantastic teams!
Bug Capture for Web Apps - Catch More Bugs with Honey (or Jam!)
Perhaps a marked up screenshot is not adequate to illustrate the bug you found and how you came upon it, and assembling a collection of marked-up screenshots comic-book style is a tedious endeavor. Our favorite resource for providing documentation on more complicated bugs is Jam (https://jam.dev/). It not only captures video of your screen leaving no ambiguity on what you did and what resulted, it also automatically includes the console and network logs. These logs provide developers with all the information they need to understand and find the root cause of the issue. We have been using Jam since their beta and it has greatly reduced the back-and-forth with our dev team, freeing up time for them to fix more bugs and tackle development on value-add features.
Bug Capture for Mobile Apps - Meet the (Test)Fairy Godmother of Bug Reporting
Mobile testing is complicated and recreating bugs takes longer than in web apps. Enter TestFairy (https://testfairy.com/) - it is similar to Jam but designed for use on mobile apps. Our team has been using TestFairy for years to reduce time to capture bugs and increase the thoroughness of our bug reports. Our development team can resolve issues much faster using the recorded video, metrics, and logs provided through TestFairy. Of note, TestFairy requires a (very small) integration by your development team.