Gone are the days of using spreadsheets, Google Docs or email to collaborate with clients on website development projects.
Using bug reporting tools is the only way forward in this day to report bugs. A bug tracking system can significantly enhance the productivity and outcomes of your website development projects, making sure they run on time and to budget.
Contents:
- What is a Bug Report?
- Examples of Good Bug Reports
- 7 Rules for Writing a Good Bug Report
- Essential Bug Report Details
- Good Bug Report Vs. Bad Bug Report Format
- How to Create Actionable Bug Reports with Bug Reporting Systems
- How to Track Bugs with BugHerd
- Conclusion
What is a Bug Report ?
Bug reporting is an essential and continuous aspect of software development. It involves collecting, formatting, storing, and sharing diagnostic information about issues that interfere with the functionality of a website or application.
Without a robust bug reporting system, development teams can struggle to locate and fix bugs, and deliver applications that not only work — but work well.
Bug reports use text, image, and video to summarize key data about a problem. Agencies use these reports to review, analyze, and correlate information about the error, as well as to identify and resolve the source of the issue.
Ideally, anyone should be able to submit a bug report. That includes end users and non-technical stakeholders. However, that can sometimes leave your development team in a situation where they don’t have the necessary technical information to fix the problem.
To submit a good bug report, the reporter doesn’t need to know all the technical details. They just need to write an effective bug report that’s actionable.
Examples of Good Bug Reports
Example 1
Bug ID: 001
Bug description: Increase the size of the hero section.
Assigned to: Developer Dave
Status: Not started
Severity: Minor
URL: example.com/example
Screenshot: Provide a visual reference of the bug
Reported by: Pat, the project manager
Date reported: 31 August 2024
Due date: 3 September 2024
Browser version: Chrome 1010.681
Resolution: 1280x720
Operating system: Mac OS
Example 2
Bug ID: 002
Bug description: The hamburger menu at the top corner of the website doesn't open when I click on it.
Assigned to: Developer Dave
Status: In Progress
Severity: Critical
URL: example.com/example
Screenshot: Provide a visual reference of the bug
Reported by: John, the front-end developer
Date reported: 2 September 2024
Due date: 4 September 2024
Browser version: Chrome 1010.681
Resolution: 1280x720
Operating system: Mac OS
Using bug reporting software is the easiest way to capture bug reports, but you can also use a spreadsheet to list all the bugs. Here is a bug report template that you can use to manually capture bugs.
👉 Download a Bug Report Template here
7 Rules for Writing a Good Bug Report
Whether you're learning how to write a web or software bug report for the first time or just need some pointers, here are the rules behind the most actionable bug reports that will make fixing bugs easy for web developers.
1. Clearly Define the Problem
Actionable bug reports use clear and direct language to state the problem.
Document as much detail about the bug as possible. Include not only what happened, but when it happened. If you took any specific actions before you noticed the bug, describe them.
It’s even better if you can add screenshots, videos, and other visual proof to your bug report. Visual documentation provides more specifics and richer context.
2. Limit Each Bug Report to One Issue
Grouping several different bugs into one report might sound like an efficient approach. In reality, it makes it harder for the developer to isolate and identify the information they need to resolve an individual bug.
When you give each bug its own report. This streamlines the developer's focus and workflow. It also prevents them from accidentally conflating unrelated information from two or more distinct bugs.
3. Explain How to Reproduce the Bug
Every good bug report explains to the developer how they can recreate the reported problem, and provides relevant background information.
The scientific method is a helpful way to think about bug reporting: the bug needs to be provable. By documenting how to recreate the bug, the developer can use that information to reproduce the bug and study its causation.
Include links and any other relevant information about where the bug was found. If the bug only happens when you take action Y, but not when you take action X, state that in the report.
4. Expected Results vs. Actual Results
In order to qualify as a bug, the issue has to involve actual results that don’t match the results that were expected.
In other words, it’s a bug if the actual result is not only different than expected, but also has an adverse impact; for example, an error message. Either the product has failed to fulfill a specific expectation, or it’s producing an undesired outcome.
Consider the repercussions of the bug. For example, does it slow down the web application’s response time? Does it limit features that support the overall user experience? Explain how the bug prevents the product from delivering the results that were desired.
5. Follow Up and Provide Clarity When Requested
After you submit a bug report, make yourself available to the development team for any follow-up questions. They may also need to work with you to further test the issue and verify that their proposed solution has actually fixed the problem.
Respond promptly and provide clarity where necessary. Keep in mind that the more accurate and detailed your bug report, the less likely the dev team will be to ask for more information.
6. Record and Provide Corresponding Codes, if you can
If relevant, include the bug’s error code or message in your report. This makes it easier for the software developer to carry out the debugging process.
Some products and services are programmed with generic error messages. However, generic messages are not always specific enough to aid the crash reporting process.
If your developers built the product with error codes, include the relevant error code in your bug report. The error codes are there for a reason: to help the developers identify and correlate common problems.
7. Collect Visual Evidence
When it comes to reporting bugs and user feedback, a picture really is worth a thousand words. One or two screenshots can sometimes be more than enough to summarize the problem.
Enclosing visual evidence with your bug report reduces the likelihood that it will be misunderstood. Whenever possible, always attach an image or recording of the problem you experienced.
You Might Like: Ways to Accelerate Review and Approval for Websites and Digital Assets
Essential Bug Report Details
To improve communication and reduce misunderstandings, submit an effective bug report that includes the following sections:
1. Bug Identification Numbers
As described earlier, some products include error codes or bug identification numbers for common and expected problems.
Bug reports often have long names that reflect the bug’s context. Keep communication with your team as simple and straightforward as possible by using the bug ID number to refer to the problem.
2. Bug Title
Even though bug ID numbers are easier to reference, bug report titles still matter. Make sure your report’s title is descriptive enough that the reader doesn’t have to review the report every time in order to know what type of problem it’s describing.
The bug report title should also tell the reader whether this is a new bug, or a bug that has been previously reported or fixed.
3. Priority
Not all bugs are equal. Assign a bug severity rating to your bug report to let the developers know how urgent it is.
You can use numbers or keywords to rate the bug report’s priority. For example: 1 through 10, or low priority to high priority. Clear-cut priority ratings will support your development team’s ability to fix the most disruptive bugs first.
4. Platform/Environment
Actionable bug reports include device and operating system details, as well as information about the browser configuration in use when the bug was detected.
Some bugs occur under specific conditions. Without information about the OS, device logs, software version, or browser configuration, the developers may be unable to create or duplicate bugs — making it much harder for them to fix the problem.
When BugHerd users report a bug, they don’t have to fumble to find metadata about the device or operating system. Our bug tracker automatically updates the report with essential technical details. This automation comes in handy for clients and other product testers who may not have much technical knowledge.
5. Description
Use the description section to cover any details that were not already included in the other sections of the bug report.
Your detailed description should summarize the what, how, and when behind the bug. It helps the developer by providing deeper context about the conditions when the bug occurs.
A good description doesn't have to be technical. It just needs to be clear, accurate, and informative.
6. Steps for Reproducing the Bug
As we covered earlier, the most actionable bug reports explain what steps need to be taken to reproduce the problem. Use the “Steps to Reproduce” section to describe specific action steps with clear, direct language.
For example:
- Open the website in mobile view
- Click on the Hamburger menu
- The Hamburger menu does not open when clicked
The above steps are actionable because they tell the reader exactly what to do.
Avoid vague instructions or ambiguities, like “Try to open the website menu and see what happens.” This fails to inform your dev team if the problem is happening in desktop or mobile view (browser version), which menu has the bug (feature details), and what the original bug or issue is (the actual outcome versus the expected outcome).
7. Visual Evidence
Your bug report will be more actionable if you include an image or video recording of the instance of failure. If possible, annotate or highlight the image to draw attention to specific error messages or buggy features.
Check Out: 5 Benefits of Design Thinking for Website Design and Development
Good Bug Report vs. Bad Bug Report Format
Now that you understand what information goes into an actionable bug report, let’s talk about formatting.
Format your report so that it emphasizes information according to a strict hierarchy. Start with the basics (bug ID, bug title, reporter name, submission date) and build up to detailed information (description, steps to reproduce, actual vs. expected results). It should be easy to scan the report and find the most important information.
Below is an example of a well-organized bug report format:
Bug ID: 123
Bug description: Unable to add a new item to my cart
Assigned to: Developer Dave
Status: Not started
Severity: Critical
URL: shopperexample.com/productig/hut
Screenshot: Provide a visual reference of the bug
Reported by: Michelle O
Date reported: 22 March 2023
Due date: 23 March 2023
Browser version: Brave 2.0
Resolution: 1920x1080
Operating system: Windows
The following is an example of a bug report that lacks proper formatting and information:
Bug description: Non-functional checkout cart
Link: shopperexample.com/productig/hut
It can take time to develop an effective bug report. Thankfully, you don’t have to create yours from scratch.
Bug reporting tools such as BugHerd automate the bug reporting and testing process by documenting key metadata. Your bug reports will be faster to make and easier for everyone on your team to read.
Here’s an example of how BugHerd organizes the information in a bug report. We think it’s pretty good, if we say so ourselves.
Also: 11 Action Steps to Better Agency Operations
How to Create Actionable Bug Reports with Bug Reporting Systems
Bug reporting systems take the hassle out of the process. All you need to do to get started is install the software or open the web platform.
There are several bug reporting systems out there. The best ones are easy-to-use for non-technical users, portable, and allow unlimited bug tracking.
Pay attention to the function of the bug reporting system you want to use. When a bug appears, it should be easy for you to create a bug log, document, store, manage, assign, close, and archive each instance where a bug occurred. You should be able to easily detect whether the same bug is being reported more than once, so that you don't double up.
BugHerd is a powerful bug reporting software for web development projects. Use it to collect feedback from QAs and clients during software testing and development. BugHerd’s issue management system is perfect for tracking the resolution of a reported bug.
If you’re working on a mobile app, consider using a software project management app like Jira or Asana that has native bug reporting templates.
How to Track Bugs with BugHerd
You need an active BugHerd account to report bugs and manage each of your projects’ bug reports.
BugHerd is best suited for web applications and offers several integrations as well. Account holders can install the BugHerd browser extension for Chrome, use the BugHerd platform, or install BugHerd on their website. You will need access to the website code to install BugHerd using JavaScript.
After setting up your BugHerd account, create a project file for the website in development. All feedback, bugs, and feature requests for the project will be stored here.
Visit the website you want to review, then click the BugHerd extension to activate the sidebar. The sidebar contains action buttons to help you create a bug report, make a screen recording, or make a feature request.
Click “log a new issue” to open the bug reporting template. The software takes a screenshot when you click the report button.
Fill the text box with a description of the issue. Assign the task, set the issue priority, and add a tag. Click the screenshot to add annotations for easier understanding.
After completing the report and annotating the image, click “create task” to report the bug.
The reported bug will remain open until the development team completes the task. Any time you visit the website, you will see the task pinned to the section of the website where the problem was discovered.
Conclusion
Now that you know how to create an actionable bug report, every bug you encounter becomes an opportunity to perfect your new skill. Repetition is key. Practice as much as you can — your website builds will be better off for it.
If you need to create and track several reports, or provide your customers with a more visual and intuitive feedback system, use BugHerd to simplify the process. Happy bug reporting!
Next: 13-Step Checklist for Website Requirements Documentation
Frequently asked questions
1. How does BugHerd help with the bug tracking process?
BugHerd is a specialized tool designed to record and track feedback from websites, images, PDFs, Figma files, designs, and other documents. It will enable your clients to share contextual feedback quickly, and provide your team with the tools to manage and action that feedback. It can also be used for quality control and user acceptance testing stages of a website development project.
With BugHerd, your team can easily search existing bug databases to track, manage, and resolve previously reported issues efficiently.
2. How do I make sure I get great bug reports using BugHerd?
Tip 1:
Instead of getting customers to fill out a feedback form, make it easy for them to report bugs on a web page as they're reviewing it.
Tip 2:
Encourage users to annotate the screenshots that BugHerd automatically captures along with their feedback, and where relevant, provide feedback via video.
Tip 3:
Bug reports will be automatically funnelled into a task board so you have one central location to manage it. Arrange the feedback for easy management: Remove duplicate bugs, assign them to your team for completion, and set severities.
Comment on tasks to further clarify them with clients or with your team.
3. What makes BugHerd different from other bug reporting tools?
- BugHerd stands out with its unique point, click and pin system. It provides simple annotation features and an easy way for users to highlight and report bugs directly on a web page; speeding up the bug reporting process and reducing communication gaps between teams and stakeholders.
- BugHerd is simpler to use than most other bug tracking tools. Users can get up and running quickly and start annotating on a live website or document using virtual sticky notes which they pin directly on the element that needs to change. No other similar tools offer that function.
- BugHerd's in-built Kanban task board is a great differentiator as you're able to manage all your annotations from the one location, using the one tool.
4. With BugHerd, can I capture feedback using video?
BugHerd enables the user to provide feedback via video on multiple types of files (eg. website, PDFs, images, Figma, and other documents), which greatly assists when the feedback is not straightforward and there are multi-step interactions.
5. What level of support does BugHerd provide?
BugHerd offers various support options, including email support, in-product help documentation, and video guides. Deluxe and Enterprise plans also include priority support for quicker issue resolution.
6. Do I need to install anything to use BugHerd?
There are two ways to set BugHerd up to get feedback on a website. You can embed a JavaScript snippet into the “head” of your website or you can install a browser extension to your preferred browser.
7. Can I use BugHerd for free?
You can try BugHerd for free on a 7-day trial. No credit card is required.
After 7 days you can continue using BugHerd via one of our subscription plans. BugHerd offers different pricing plans to accommodate various team sizes and needs.
Start a free 7-day trial or book a 1:1 demo
8. What is the pricing structure for BugHerd?
BugHerd offers different pricing plans to accommodate various team sizes and needs. You can find detailed information on the pricing page of the BugHerd website. BugHerd also includes a free 7 day trial. There are no limits on the number of projects or users that can be managed with BugHerd, ensuring scalability and adaptability.
