Software bugs are like real bugs: no one likes them, but they're a fact of life and you need a way to handle them when they show up.

While engineers are responsible for preventing and addressing software issues, anyone can take part in improving the apps they use by helping to report when things don't work. Those who work at tech companies especially should recognize that helping to improve the product is part of being a good team player. “If you see something, say something”, as the saying goes.

The problem is, most non-technical folks are never really taught how to communicate with technical teams to get things fixed. This article was written to be the resource I've often found myself wanting to be able forward: a guide on how to be more effective in this particular area of tech partnership. I’ll share some insights from the engineering perspective to give you an understanding of what makes a good bug report and why. Put these points into practice and your issues will likely get resolved faster, you'll have a better relationship with your tech team, and hopefully we'll all encounter fewer bugs in the apps we use.

The Bug Process

The purpose of a bug report is to clearly explain an observed issue, provide context, and detail the steps taken to produce it so that a technical team can identify its root cause and implement a resolution.

A good report is one that helps gets an issue resolved most efficiently. To give you a sense of what this process typically entails at a software company, I’ve summarized a general issue workflow visually:

The key takeaway for you, the bug reporter, is that when you submit an issue you're creating a task runs through a multi-step communication flow. Minimizing inefficient loops and stalls in this workflow heavily depends on the information that seeds it. Therefore, the one thing to remember when it comes to reporting bugs is this:

The better the quality and quantity of the information you provide, the faster and easier it is to fix the bug.

Unfortunately, the most common reason for slowdown in an issue's resolution is getting labeled with "needs more info". Every engineer has sighed at a bug report with little more information than: "it didn't work". Hint: you don't want your issues falling into these categories. So what information should you, the good software citizen, provide?

Provide Context

First, provide as much context as possible. Your objective is to assist the investigating engineer, and their first task will be to piece together a clear picture of what happened. To do this, they'll typically combine your firsthand account of events with additional internal information, such as system logs and source code logic. The context you provide helps to quickly connect and correlate between these two sources. Some examples of contextual information that's commonly useful:

  • Account Identifiers - Your account email, username, or organization
  • Time and date - When the incident occurred
  • Location - A web URL and a description of the app screen you were on
  • App/Platform - Your web browser, mobile platform, or operating system
  • Version - The version of the software you're using

Sometimes software works exactly as it was intended to, but the behavior differs from what you expected.

You'll also want to provide qualitative context about the issue you're encountering, as a fair amount of reported “bugs” turn out not to be technical issues at all. Sometimes software works exactly as it was intended to, but the behavior differs from what you, the user, expected. These "user error" scenarios indicate a communication or UX shortcoming in the product, and require design thinking to address. Therefore when reporting something you believe to be an issue, include context on what you were trying to accomplish and what you expected to happen. This will help inform product owners in cases when an appropriate solution needs to be designed, not just implemented.

Overcommunicate

Describe the issue you're encountering by being as specific and detailed as possible. Seriously, overcommunicate. A good target is to try not to get asked for follow-up information on an issue by providing as much you can up front. The higher fidelity you can make your descriptions, the more engineers have to work with. Pictures are worth a thousand words here, so include screenshots and screenrecordings if you can.

Consider a user's hypothetical bug report for a rideshare app: "I'm unable to take a trip". As an engineer seeing this, I'd have a slew of questions I'd need to ask the submitter. Are you unable to sign in? Does the app crash when you start it? Are you able to take trips in some cases but not others? What error message do you see when this happens? The answer to each of these questions has major implications on where the problem lies, the urgency of the issue, and how to proceed with investigating.

Contextual information and clear descriptions help narrow the search down to potential suspected areas.

To give you some more insight behind the engineering curtain: a majority of software bugs occur due to the release of new updates, and therefore solving an issue is often first a hunt for recent suspicious code changes. Contextual information and clear descriptions help narrow the search down to potential suspected areas. For example, if you're having trouble changing billing settings on a mobile app, an engineer aware of a recent migration in the payment systems might jump straight to that section of the codebase, verifying your report against changes in the relevant timeframe.

By providing context (the "who, what, when, where, why") and specific, detailed information about your issue, you help engineers to better triangulate the source of the problem you're experiencing.

Detail the Steps to Reproduce

While context is helpful, the most valuable information you can provide is a clear set of steps to consistently reproduce the observed issue. This isn't always easy or possible, but you as the person experiencing the bug are in the best position to obtain this key information.

When you encounter a software bug, think of yourself as having taken an unexpected turn off the main path in a product's figurative forest. Most bugs don't hide in plain sight, because if they were obvious they'd likely have been caught before reaching the wild. Software issues typically manifest because of an unexpected sequence of actions or a specific combination of conditions - what engineers call "edge cases". Each bug you encounter appears as a result of the specific steps you took, at a point in time, under a set of unique conditions that applied to you. Recreating all these factors to consistently arrive back at this spot is the key challenge; your goal is to provide instructions that will help a bug catcher do so.

The reason that these steps to "repro" an issue are so valuable is that the key to cracking a bug is figuring out exactly why the failure mode is occurring. Without understanding why an issue exists, engineers can't effectively reason about and implement a solution. Once an engineer can consistently reproduce a bug however, the battle is often half won, as the root cause is significantly easier to deduce when an error can be repeatedly observed. Theories can be tested by tweaking conditions, repeating the steps, and observing results. The critical thinking involved in this part of the process is usually the core work of solving an issue, as writing a code fix is a relatively easier task.

Providing clear, specific steps to help engineers see an issue for themselves will dramatically increase the speed at which your bugs are squashed. So the next time you encounter a bug: pause, make a detailed observation of your context, and do your best to retrace and document the steps you took to get there.

Communication Tips

In addition to describing what went wrong, you should communicate the impact an issue has on your ability to use the product. Describe what tasks you weren't able to accomplish, the frequency and severity of the issue, and whether you were able to find a workaround. This informs product owners who need to prioritize your issue against the total backlog of work. Note that exaggerating your issue’s severity in hopes of expediting a fix isn’t particularly helpful to the objective reviewer, and avoiding hyperbole gives more credibility to your requests as a whole.

Another recommendation is to clearly separate your theories about why an issue occurs from objective, factual observations. Your hypotheses can be helpful, but they'll always be conjecture as you can't see the source of truth in the underlying systems. The risk of mixing these in with the facts is simply that you might confuse or mislead engineers. While developers can usually filter out extraneous information, they're still susceptible to getting sidetracked investigating false leads. Therefore, you can include your prognoses, but call them out as a theories separate from the observed symptoms. Avoid sending engineers on wild goose chases.

Lastly, a quick note on tone. No one likes it when things don't work, and feeling annoyed while reporting an issue you've just experienced is completely understandable. Like any customer support request, however, keeping a courteous tone will serve everyone best here. For the responsible technical team, having mistakes labeled and assigned is usually humbling enough without the extra attitude. When it comes to software bugs, the old adage "you catch more flies with honey than with vinegar" still applies well.

Concluding

Technology and team processes are of course constantly improving to better detect and prevent software issues from impacting users in the first place. But as long as we have complex technical systems designed by fallible humans under time constraints, we can expect bugs to exist. And these bugs will be encountered and squashed by people who need to communicate with each other.

While most of our discussions on improving software revolve around computer systems, all software is also fundamentally intertwined with a human system comprised of the people who care about its creation and utility. As a user, you can choose to be an active, helpful agent - an antibody in the product's immune system. My hope is that reading this article will contribute in some small way to that choice. Because, especially in this day and age, a world with fewer bugs - that's something we can all get behind. ∎

Appendix: A Bug Reporting Cheatsheet

Here's a quick reference for bug reporting you can customize for yourself or your team:

Remember
Be detailed and specific. Overcommunicate.
Separate out your theories from observations
Keep a courteous tone

Provide context
"Who, what, when, where, why"
Account identifiers, date and time, location
Include screenshots/recordings

Describe
What you did
What you expected to happen
What actually happened
Provide steps to consistently reproduce the issue

Impact
How is this impacting your usage of the product?
Did you find a workaround?