It often takes longer to write a bad bug report than a good one. A bad bug report will save you some time up front but only delays the inevitable. If a developer has to ask you for additional information, that holds up their progress, and you face an interruption right when the bug is no longer fresh in your mind.

But if you file a good bug report up front, you’ll make everyone more efficient. The best way to write great bug reports is to get your head around the ingredients that make up a perfect bug report. These tips will help you write your best possible bug reports—your bugs will be fixed faster, and requests for additional information will become few and far between.

1. Report Them

It may seem obvious, but the most important step of tracking bugs is to record them in the first place—if you don’t report them, they can’t be fixed. A bug that may seem minor or obvious to you might be elusive or easily neglected by someone else, so don’t worry too much about whether someone else has already noticed it. That’s not to say that you shouldn’t check to see whether an issue has already been reported, but if you can’t find it or you aren’t sure, go ahead and log it just to be safe. When a developer faces a bug that’s particularly difficult to reproduce, those duplicates can sometimes be the key to finding a common thread and solving the problem.

2. One Bug per Issue

Each issue ultimately needs to be resolved and closed. But if an issue covers multiple bugs, it becomes that much harder for developers to keep track of the moving parts as they try to fix each piece—because instead of perhaps three bugs, it now only looks like a single bug—and that’s how bugs can fall through the cracks. And it’s not uncommon for team members to be responsible for distinct areas of an application, so by filing separate issues instead of a mega-issue, you also gain the flexibility to give each issue a unique assignee and priority.

If any of your existing issues cover multiple bugs, you should split them into separate issues so they can be addressed individually. But since splitting issues leaves room for mistakes, confusion, or other misunderstandings, you’re better off filing them as individual issues right from the start. If you need to convey a relationship among a set of issues, include references from each issue to its related issues.

3. Use Descriptive Subjects

When someone looks through a list of issues, the issues’ subjects are the most important identifying information they see. Think of each issue’s subject as its name. In real life, for instance, you wouldn’t refer to your best friend as “the person” since that could refer to anyone—you’d use your friend’s name instead. The same goes with issues. A subject of “Broken Login” doesn’t convey what part of the login screen is broken or at which point it failed. But a subject like “Can’t log in because I’m missing a user account” wipes out that ambiguity. Clear and accurate subjects make it easier to locate specific issues and quickly understand what they’re about. They’ll make your team more efficient and help them resolve issues more quickly.

4. Write Clearly

The majority of communication around bugs or issues is text. So good writing is central to filing great bug reports. Use conversational sentences that clearly describe the problem, and try to steer clear of business-speak. You may find it helpful to imagine that you’re sitting next to the other person and talking them through the bug: then just write down those words that you’d say to them in real life and put them in the issue. So for instance, rather than filing an issue that says, “Administer the configuration of newly acquired mail server,” you could say, “Configure our new mail server.” (After all, that’s how you’d say it in real life.) Obtuse language can cause misunderstandings and other errors, and that can lead to bugs down the road or additional back-and-forth requests that can take up your time and hamper your progress.

5. Focus on the Facts

It might be tempting to speculate on what you think might be causing a problem, and there are occasions now and again where that can be helpful. But more often than not, those hunches can end up being a red herring that can send a developer down the wrong path, making it more difficult for them to get to the bottom of things. It’s generally better to stick to the facts about a bug rather than trying to guess what might be causing the problem. That’s not to say that you shouldn’t ever speculate, but do so sparingly and only when your guess is more of an educated guess gleaned from observable behaviors.

6. Describe Your Expectations

There’s a simple format that’ll help you write great bug reports. At times, this format may feel like overkill, but it can make a world of difference toward improving your bug reports. The format revolves around two questions:

What did you expect to happen? Some bugs may be subjective. And if you’re reporting an issue without clarifying what you expected to happen, you might get a response like “working as designed” or “this looks fine to me.” So when you’re filing an issue, include a sentence or two on what you’re expecting to happen, and that’ll make it easier for developers to understand what you’re looking for.
What actually happened? So you came across a bug. Did you see any errors along the way? Or did you have a chance to grab a URL or screenshot for the page you were taken to? When an issue is hard to reproduce, sometimes a screenshot or an error message can be the key to solving the problem.

For instance, an issue that just said “I can’t log in” or “login is broken” would leave a lot to the imagination, and the developer working on it would probably need some clarification. Adding a little more detail in your initial reports can help reduce the chances that developers will have to ask follow-up questions later.

Let’s consider this revised report about the same problem:

I’m at (URL) and I’m trying to log in using my username, (username). But the system is saying that my username can’t be found, and it’s taking me to (URL).

That report would take only a moment longer to write, but it eliminates any gray areas, so there’s no question in the developer’s mind what’s wrong. Providing information like screenshots, URLs, and specific error messages can potentially shave hours off the time it takes to fix an issue.

While many bugs are easy to reproduce, that’s not always the case. It’s safer to assume that the folks trying to fix a bug won’t be able to reproduce the problem on their end. There are a couple of tricks you can use to help you capture most (if not all) of the steps to reproduce an issue:

Document each problem as soon as you encounter it. Then try to reproduce the problem based on the steps you just wrote down.
Even if you can’t reproduce the problem, it’s still worth reporting. Sometimes multiple reports of a ghost issue are the only way a developer can track it down.
If you can consistently reproduce a problem, take your steps to reproduce the issue and whittle them down to the simplest sequence that still triggers the issue. And if you can include screenshots or video to help illustrate the steps you’re going through, that can really help.

Developers often face overwhelming numbers of possibilities when they’re debugging issues. And if a developer can’t reproduce a bug, it may be difficult, if not impossible, to fix. So when you’re filing an issue, describe what you were doing when you came across it and include detailed steps to reproduce it—that’ll help ensure that the issue can be resolved quickly.

8. Provide These Key Details

Certain types of information can be extremely valuable to developers when they’re working through an issue. While these bits of information aren’t always strictly necessary, they make a difference often enough that they’re worth mentioning.

Screenshots

Pictures are worth a thousand words, and a screenshot is frequently the single most helpful piece of information to a developer trying to fix a bug. If you’re not familiar with taking screenshots, take some time to learn how to take screenshots on your computer in a way that’ll make it easy for you to include them in bug reports. Just remember—a screenshot isn’t a substitute for words. It’s still helpful to write up each issue because developers might not be able to infer an issue based off a screenshot alone. (On top of that, text like “The login screen isn’t accepting passwords longer than 8 characters” is way more search friendly than an issue with just an attachment named broken.jpg.)

URLs

If you’re testing a web-based application, copy and paste the URLs for each issue you come across. URLs often contain bits of data that can help developers diagnose issues at a low level. And if your issue involves an error message, it’s often helpful to provide not only the URL where you saw the error but also the URL for the page just before you got the error. It’s not uncommon for bugs to originate in a page just before an error rather than the page displaying the error.

Error Messages

If you receive an error message that seems to be a bug, the contents of that error message are gold. Whether it’s a user-friendly error message or a system-generated error message that looks like gibberish, it’s worth including in your report. What may look like gibberish to you is often a critical piece of information to a developer.

Details about Your Environment

You might be surprised by how many bugs only come to light once you start testing across a wide variety of browsers and devices. Some bugs might only show up on Windows while others might only happen on Macs. The same goes for Android and iOS. Or something might not work in Firefox but work perfectly in Chrome. So when you’re reporting an issue, it’s generally good practice to include your browser and operating system information. If you’re not sure which browser or operating system you’re using, ask someone to help you figure it out, and keep it handy for easy copying and pasting into your bug reports.

A bug tracker is ultimately only as good as the bugs that get filed. Thoroughly documenting and reporting bugs will save time for both you and the developers you work with, and it'll ensure that your bugs are resolved more quickly. It may take an extra moment, but it's worth the up-front investment.