How to Write a Bug Report: The TA Digital Way
Feb 21, 2018
At TA Digital, we like to think of a software bug as something more than just a problem or defect. We think of bugs as opportunities. Finding a bug means that you have a chance to build a better product — a product that’s more engaging, represents your company better and helps you forge deeper relationships with your customers. If you want to enjoy the benefits that a bug discovery can bring to your organization, though, you need to document and report the bug in a positive and proactive way. Proper bug reporting requires a little extra work, but the rewards for doing that work are great.
Today, we’d like to share our procedure for reporting bugs at TA Digital.
What Basic Information Should a Bug Report Contain?
We believe that every bug report should answer these basic questions.
- Is the bug reproducible or seemingly random? What actions cause the bug to occur?
- Do you have to perform all of those steps to trigger the bug, or does the bug still occur if you omit certain steps?
- Does the bug happen only when certain software settings are enabled?
- How critical is the bug?
- Is it possible to trigger the bug in other ways?
- Does the software behave in other abnormal ways after the bug has occurred?
Providing as much information as possible about what the bug is and how to reproduce it is the best way to ensure that you won’t have to wait long for a resolution.
Write the Bug Report for the Reader
When you write a bug report, it’s essential to consider the knowledge level of the people who will read it. If the only people reading bug reports in your organization are developers who know the application as well as you do, it’s okay to litter your report with jargon and abbreviations. In some companies, though, management personnel, documentation writers, testers and support staff may all read bug reports. If that’s true of your company, you may need to avoid jargon and add further detail. Will some of the readers be offshore personnel who don’t share your native language? You may need to use simpler words.
In some cases, companies distribute bug reports to end users. If that’s true of your organization, you’ll need to choose your words carefully to avoid using negative language or disclosing secrets. If end users will see your bug report, you may need to write two versions of the report.
Report One Issue at a Time
If you’ve discovered multiple bugs in an application, each one requires its own report. Trying to combine several bugs in a single report will only overwhelm the developers tasked with fixing those bugs. In the end, it’s unlikely that every bug in the report will get fixed.
Write an Informative Title
The developers in your organization may receive bug reports from many users. Until a developer reads a report, all that he sees is a one-line title. When a developer sees a summary screen with many titles, he’ll open the report with the title that seems most severe. When you write a bug report, you should try to keep the title as concise and informative as possible. Don’t write about the severity of the bug in the report’s title; that information will be in another field. Save the title field for the most essential information. A good bug report title explains the issue and describes the element of the program that has the issue. “Clicking the ‘Send’ button crashes the program,” for example, is a good title.
These are a few examples of bug report titles that don’t provide enough detail followed by improved versions of those titles.
- “Window resize issue” could become “Images get cropped when window is resized”
- “Close button issue” could become “Had to press close button twice to close a popup”
- “Change title in component” could become “Changes to the ‘Title’ field don’t take effect when clicking ‘Save'”
Write a Concise Description of the Problem
Help your organization’s developers use their time efficiently by keeping your bug reports short and to the point. In no more than a paragraph or two, describe the problem fully and explain the steps necessary to reproduce it. These are some of the questions that your bug report should answer if possible.
- Does the bug happen on other machines, or does it only happen on your machine? What is unique about your computer’s hardware or software configuration?
- Does the problem occur only with a certain combination of configurations or settings?
- Did the problem appear after a recent software update?
Remember that the developers in your organization may not know the application from the user’s point of view as well as you do. Your bug report should explain how what occurs in the software differs from what you expect to occur.
Explain How to Reproduce the Issue
No software bug is truly random, and a developer can only fix a problem that he can see. Before writing a bug report, try to get the problem to occur on your computer more than once. Record the exact steps that allowed you to reproduce the bug. When you reproduce the bug on your machine, try omitting certain steps to see if the bug still appears. Your goal is to arrive at the minimum number of steps required to make the bug appear. Your report, as a result, can omit the irrelevant steps. If you can’t reproduce the bug reliably, it’s okay to mention that in your report. Remember, though, that a bug that’s difficult to reproduce may be difficult to fix.
Document Error Messages Fully
When the bug occurs, does the application display an error message? An error message often contains debugging information that can help your developers track down and resolve the issue. Include the full text of the error message in your report. If the application saves a log file on your computer, attach the log to the report.
Include Keywords for Faster Searching
Your company’s bug tracking system may allow developers to search for text within the fields of problem reports. Include as many keywords as possible in your bug report to make searching easier. Your developers will use the search function to find reports describing the same issue and link those reports together.
Explain the Impact to the Company
In an organization with limited IT resources, developers must address software bugs in order of their severity. Have you discovered a bug that could directly impact the profitability of your company or harm the customer experience in some way? Include that information in your report so your company’s developers can understand the impact of the bug.
Include Relevant File Attachments
Your company’s developers may not have the time or ability to view the bug as it appears on your computer. If showing the bug to your developers could help them resolve the issue, attach a screenshot to your bug report. A screenshot may be especially valuable if describing the issue fully with text would make the bug report too cumbersome to read. Remember, though, that a screenshot can’t replace an outline of the steps required to reproduce the issue. It’s also wise to check the folder for the application on your computer to see if the application recorded the bug in a log file.
State the Facts Only
Unless you are an expert user of the application, it’s unwise to speculate as to the root cause of the bug. An incorrect speculation may only result in wasted time as your developers look in the wrong place when trying to track down the source of the problem. Keep your report factual unless you have data to verify that your hypothesis is correct.
Search for Similar Reports
Does your company allow all users to view the bug tracking system? If so, it’s wise to search the system using several keywords related to the bug you’ve discovered. You may find that others have already reported the same bug. Submitting a duplicate report is wasteful of your developers’ time. In some companies, you may even be penalized for submitting a bug report when a duplicate report exists. Your developers will find your insight helpful, though, if you have information to add to an existing report.
Be a Team Player
In any corporation, the users and developers are on the same team. You have nothing to gain by cultivating an adversarial relationship with the people tasked with making your job easier and helping you to be more productive. Read your bug report carefully before submitting it to ensure that you aren’t using harsh, critical or negative language. Negative language will only hurt morale among your company’s developers — and it won’t cause your developers to fix the issue more quickly.
Explore Additional Resources
Learn more on how to select the Right CMS for your business and excel the Digital Experience.
Our Quality Assurance team helps our clients build a managed QA department.
GET HELP FROM OUR EXPERTS
Over the past 19 years, we have completed thousands of digital projects globally. We have one of the largest and deepest multi-solutions digital consulting teams in the world. Our proprietary processes and years of Digital Experience expertise have earned us a 97% customer satisfaction rating with our clients ranging from Global Fortune 1000 to Mid-Market Enterprises, leading educational institutions, and Non-Profits.
About TA Digital
TA Digital is an innovative digital transformation agency, specializing in delivering digital experience, commerce, and marketing solutions. For nearly two decades, we have been helping traditional businesses transform and create dynamic digital cultures through disruptive strategies and agile deployment of innovative solutions. We are known as a global leader in the digital technology industry for helping marketing leaders achieve their revenue targets, create profitable, omni-channel customer and commerce experiences. TA Digital has high-level strategic partnerships with digital technology companies Adobe, Microsoft, Sitecore, Acquia, Marketo, SAP Hybris, Elastic Path, IBM Watson Marketing, Coveo and Episerver. The company was named on 2013, 2014, 2015 Inc. 5000 list as one of the fastest-growing technology companies in the United States.