Avoiding putting in the effort up front may help file the issue faster, but it’s likely the developer will still need to request additional information. So, skimping on details is generally only delaying the inevitable. It’s best to put in the time up front to file a good bug report, and everyone will be more efficient.
Ultimately, every bug is different, and all of this information may not be required every time, but this should help provide some context to writing the best possible bug reports.
Report Them
It may seem silly, but the single most important part of bug tracking to make sure they get into the system. Even the smallest or most obvious bugs are often times rare or otherwise easy to miss for a variety of reasons. The important thing is that if you see a bug, file it. Don’t worry about whether it’s a duplicate. It’s important to get it into the system. In a lot of cases, a particular bug may be difficult to reproduce, but if several instances are reported, it’s easier for the developer to find a common thread and solve the problem.
Only One Problem Per Issue, Please
Each issue ultimately needs to be resolved and closed. If a single issue lists multiple bugs, then there’s no way to close one of the bugs if the other two are still open. As a result, the issues need to be split into several issues so that they can be closed individually. This creates room for mistakes, confusion, or other misunderstandings if any information is lost when splitting the issues. Also, different team members are often responsible for different areas of an application. So, by dividing it into separate issues, you’re also enabling each issue to be giving a unique assignee and priority.
For instance, a bad issue would look like…
The login form doesn’t work. The forgot password form is saying my user account doesn’t exist. The link is broken to return to the login form.
While a good issue would split each of those into three separate reports so that they can be handled individually. Then one person could handle the broken link issue quickly while a different developer can look into the login form issues.
Tracking Bugs & Issues Should Be Easy
Overly complex issue tracking software makes work hard. Sifter helps software & site development teams focus on doing what matters.
Use Descriptive Subjects
When viewing a list of issues, the subject is the most important identifying piece of information. Think of it like the issue’s name. For instance, you wouldn’t refer to your best friend as “the person”. That could be anyone. You’d want to use your friend’s name. The same goes with issues. “Broken Login” isn’t detailed. “Can’t login due to missing user account” is much better. The more descriptive and accurate that it is, the easier it is to both locate a specific issue and quickly understand what it’s about. That helps make the team more efficient and means quicker resolutions on issues.
Write Well
The majority of communication around a bug or issue is text. So, it would make sense that writing is one of the most important pieces of filing a bug report. It’s always helpful to use complete sentences and make an effort to clearly identify the problem. Any lack of clarity in the communication can lead to misunderstanding or other errors. That can lead to requests for more information which take time and can drastically slow down the resolution process.
Focus on Facts
It’s often tempting to suggest or speculate what you think the problem may be, and at times, this can be helpful. However, more often than it not, it can be a distraction and actually make it more difficult for the developer to get to the bottom of things because it may send them down the wrong path. So it’s generally better to focus on objectively reporting facts about the bug rather than trying to guess what the source of the problem really is.
The Bug Reporting Format
Beyond writing well, there’s a simple format that you can rely upon for writing great bug reports. Remember, developers aren’t mind readers, and sometimes it helps to really spell things out.
- What did you expect to happen? This is important. Some bugs are really just subjective usability issues. Reporting an issue without clarifying your expectations may lead to a “working as designed” response. However, with the added clarification of your expectations, it’s easier to understand the anticipated behavior and determine whether it’s truly a bug or a usability issue that needs to be reviewed.
- What actually happened? Did you see any errors? Do you have a URL or screenshot for the page to which where you were ultimately taken? Sometimes, when an issue is diffuclt to reproduce, seeing a screenshot or knowing an error message can be the key to solving the problem.
For instance, saying “can’t log in” or “login is broken” doesn’t help, and the developer would invariably need to request more information. Those are very open-ended and leave a lot of room for possible problems. However, adding a little more detail could really help. Here’s an example of a better bug report. It’s still brief, but it provides just enough additional information for the developer to dig in.
I’m at (URL) and I’m trying to log in using my username, (username). However, the system is saying that the username cannot be found and taking me to (URL).
Beyond that, anytime you can provide screenshots, URLs, error messages, or any additional information it can work wonders helping the developer get to the bottom of things. Even the smallest detail can be useful when tracking down a difficult to reproduce bug.
Document Steps to Reproduce
It’s always important to expect that the people on the other end will not be able to reproduce the problem. There are too many potential variables involved. If a bug can’t be reproduced, it can be incredibly difficult, if not impossible, to fix. By providing the context of what you were doing when it happened as well as the minimal steps you followed to createt he issue, you’re ensuring that the issue can be reproduced without much effort.
First, always document the problem as best you can as soon as you encounter it. Then, try to reproduce the problem. Once you’ve reproduced the problem, document the minimum sequence of events that’s necessary to reproduce it. If you can, make sure to include screenshots or video.
Provide Additional Relevant Information
Finally, it’s helpful to understand the types of information that can be extremely valuable to developers when reporting an issue. These bits of information aren’t universally helpful, but they make a difference often enough that they’re worth mentioning.
URLs
If it’s a web-based application, providing the relevant URLs is amazingly powerful. URLs often contain bits of data that can help the developer track an issue down to a very low level. With URLs, it often also helps not only to provide the URL where the error occurred, but also the URL for the page you were on just prior to the error occurring. The more URLs, the merrier.
Error Messages
Anytime there’s a bug, and an error message of any kind is displayed to you, the contents of that error message are very important. Wether it’s a user-friendly error message or a system-generated error message that looks like gibberish, those error messages go a long ways in helping a developer understand what happened.
Operating System, Web Browser, Device, etc.
One of the most common sources of bugs is the variation in different platforms. Some bugs might only occur in Windows while others only happen on Macs. The same goes for Android and iOS. Then something might be broken in Firefox but work perfectly in Chrome. So when reporting an issue, it’s generally helpful to include your browser and operating system information.
Summary
A bug tracker is ultimately only as good as the bugs that get filed. By taking some extra time to thoroughly document and report bugs up front, you can save time and ensure that the bugs are resolved more quickly and with less back and forth. It may take a few extra moments, but it’s almost always worth the up front investment.