What is a bug report? Well, that depends.
It could be a highly valuable document that provides crucial information that can be used by developers to improve the robustness of their software product…
…Or it could be a massive waste of time…
…Or a lot of interesting data that means nothing to anyone.
Bugs are a fact of life for any developer. You just can’t call yourself a programmer or a developer until you’ve written software with a bug in it. For many of us, that may very well have started right back at the ‘Hello World’ stage when you realized you were using the wrong variable type, the wrong speech marks, missing a semicolon, or failing to perform the correct dance routine for the delight and pleasure of the warped mind that came up with the syntax rules for the programming language you’re using.
So let’s not dream of a world in which bugs don’t exist. And let’s not just shrug them off with the old, “It’s not a bug, it’s an unexpected feature”.
Yeah, right. That’s fooling nobody. 😂
Bugs aren’t something to be afraid of really. They can be hugely valuable, showing us how we can improve our code and make it more robust, and a better quality end product.
The truth is that you can’t possibly test software under every possible condition. From hardware differences to software conflicts, and from out of date systems to unanticipated uses – end users are impossible to predict.
So bug reports are a vital way of transforming all of your end users into testers, providing you with a wealth of information that you can use to improve your product.
At least, that’s how it should be.
But that’s only if the bug reports you get are meaningful, useful, and can be used to identify the cause of the issue and allow you to rectify it.
A bug report that simply says, “Software crashes when I try to run it” doesn’t help you at all. Similarly, messages along the lines of “Doesn’t work”, “Crashes when I click the button”, and “Won’t let me go back when I click the button on the screen I was using” are all worthless.
It’s also worth bearing in mind that having a really good, clear, and effective bug reporting system available to support your product helps to instill greater confidence in your product, because it will be clear to customers that you take the maintenance of your product seriously.
If it’s evident that you care about getting a full and proper bug report, because you genuinely want to identify the problem and fix it, then customers are not only more likely to take the time to file the report, but will have greater confidence in your service and software product in the future. Especially if they see changelogs and updates reflecting previous bug reports from others.
So what makes a good bug report?
In this article we’re going to lift up a few rocks, and discover the world of bugs. We’ll examine exactly what a bug report should be, how a good bug report should be designed, what information to include, and share some examples of great bug reports. We’ll also show you how to go about implementing a top-notch bug reporting system.
So slip on your gardening gloves, and let’s get friendly with the mini-beasties. 🐞
The Anatomy of a Bug Report
Diving into the world of bugs and reports can feel a little like exploring a dense jungle. But bug reports are like maps – properly laid out, and with all of the right information, they can serve as invaluable guides to help us navigate the thickets of software anomalies. So what features need to be included in such a map, and how should a good bug report be structured?
Title or Summary: Your Bug’s Headline
Just like a newspaper headline, the title needs to be clear about the nature of the bug report, its severity, the level of urgency you need to assign it, and perhaps even the team who would be best reviewing it.
Simply having every bug report being submitted with the title “Bug Report” says nothing. Of course, if you only receive one of these every couple of weeks, it wouldn’t matter too much. But what if you have hundreds, thousands, or even tens of thousands of users, potentially filing hundreds of reports every week?
If it’s a new release, then this is perfectly possible, and so the heading or title needs to be considered carefully, for the value it can offer.
Priority and Severity: The Urgency and Impact Scale
When you lift up a rock and spot a bug, there are often telltale signs that tell us right away whether it’s harmless, or something to be wary of. If it’s marked with yellow, it’s likely going to hurt us if we prod it.
These instant markers are essential in the animal kingdom, and it’s also true for bug reports, because having a clear indicator that tells us exactly how serious the issue is, how dangerous it would be to put it on hold, and how much it could potentially hurt if we do nothing is vital.
Having a clear way of identifying the urgency of a problem, and the impact it could have on the product, business, or brand, is a crucial way to ensure the most serious issues are prioritized correctly. It’s all about managing resources and expectations. And not getting stung.
Environment Details: Setting the Scene
Lift up an old log and you know you’re likely to find pill bugs (or woodlice). And you know that under a rock you’re likely to find ants, millipedes and beetles, and nearer a pine tree it’ll be weevils.
In much the same way, a good bug report should help you identify where the bug lives. Where can you find it? This includes understanding things such as the operating system that was being used, the browser type/version, and any relevant hardware settings.
The more details included in a bug report, the better the chance of narrowing down where the problem lies so that it can be identified correctly, and addressed.
Steps to Reproduce: The Treasure Hunt
This is where a good bug report leads the developer straight to the problem. Just like a treasure map that leads you directly to the golden tortoise beetle (yes, that’s actually a thing), a bug report should identify the specific steps that led to the problem.
These instructions need to be clear and precise, so that the developer can follow the exact same steps, to try to recreate the problem. In combination with the information in the previous step, this should help to reproduce the issue, and allow for a proper investigation into the cause.
Expected vs. Actual Results: Reality Check
It’s easy to joke about the “it’s not a bug, it’s a feature” clause, but the reality is that sometimes it may not always be clear what’s supposed to happen. If it doesn’t match up with expectations, then is it a bug? Or an oversight?
The next essential element to include in the bug report is the provision of critical context – what did the user do, what did they expect would happen, and what actually did happen?
This is where you can identify whether the issue is an actual bug, a case of poor user interface design, an oversight as far as the user experience is concerned, or an actual feature that was planned, but perhaps unwisely.
Visual Proof: A Picture Is Worth a Thousand Logs
The power of an image is everything – as evidenced by the success of visual platforms such as Instagram and TikTok.
I could tell you why the Chrysina Aurigans is my favorite insect because of its mesmerizing beauty, but you’re unlikely to be impressed… until you actually see a photo of one (go on, Google it now, but be sure to come straight back here!).
A great bug report doesn’t rely solely on words, but also on images – screenshots of the software in action. A screenshot can tell a developer a lot more about the problem, as it will often include details that may seem unimportant or irrelevant to the user, but which help shed light on the cause of the problem to the developer.
Perhaps a particular combination of selected options, the inclusion of unexpected symbols in a text field, the disabling of an option – any of these could help explain what the bug might be, but which may be entirely overlooked by the user when filling in the bug report.
Common Mistakes to Avoid
Bug reporting is a tale of two sides – and it’s the combined roles of both developers and reporters that ultimately decide on the effectiveness of the report in helping to drive your product forward.
Developers have a vital role to play in making sure that the bug reporting system works well, and facilitates the most effective means for capturing the essential data, and helping users submit the right information.
For example, we’ve seen too many instances of people submitting bug reports that either allow the user the freedom to submit whatever title they like, or other systems that submit all bug reports with the same title – usually something helpful like “Bug Report”!
If the title option is too open-ended then customers may often start to describe the issue or just include a complaint. Neither of which helps the development team prioritize the issue. Instead, including a list of titles from which the user can choose provides them with more flexibility, but at the same time helping the developer apply a severity rating to the problem, and even have it assigned to the relevant team. Implementing an automated system that does this can really help.
We’ve also come across reporting systems that consist of large text boxes that encourage the user to write an essay. Instead, having a template that breaks the report down into a series of options or questions helps guide the user through the submission process, ensuring that the developers have all of the right information. A bug report that’s missing vital information doesn’t help the developer, and wastes the user’s time.
The other issue with having a bug reporting system that’s too open-ended is that there can be a tendency for subjective language to creep in. Reports that include statements such as “I don’t like how this looks”, “It feels slow when I use it”, or “It’s a bit confusing” all demonstrate a need for further revisions to the product, but don’t provide any real indication of the issue or cause. Again, having a template to complete makes this subjective language much less likely to appear, providing more value to the developer.
For developers looking at implementing or revising an effective bug reporting system, we would advise implementing the following four features:
Template and Guidelines: Provide a structured template for bug reports that prompts users for all necessary information. This can include tooltips or examples for each field to clarify what’s needed.
Validation and Mandatory Fields: Implement a form validation system that requires users to fill out every essential field before the form is submitted. This makes sure that reports aren’t ever too vague or missing key details.
Education and Examples: Offer a brief tutorial or FAQ section on how to write a good bug report. Including examples of both good and bad reports can demonstrate best practices and common mistakes to avoid.
Feedback Loop: Create a system where developers can request additional information from the user without leaving the bug-tracking environment. This not only speeds up clarification but also educates reporters on what information is valuable.
Tools for Bug Reporting
There are a number of bug reporting tools available (a cursory search on Google reveals a quarter of a billion results), but based on our experience, and that of partners and clients with whom we have worked, this is our shortlist of the best bug reporting tools you should consider if you’re part of a developer team keen to do plenty of prompt bug squishing.
Jira
Use as a Bug Reporting Tool: Jira is extremely customizable, allowing teams to create specific issue types for bug tracking. It uses custom workflows that define the lifecycle of a bug, all the way from identification through to resolution. Teams can set up custom fields to capture all of the relevant bug details, prioritize them, and then assign them to the most appropriate team members.
Unique Features: What sets Jira apart is its deep integration with the software development lifecycle. It supports agile methodologies such as Scrum and Kanban, offering boards that track the progress of bug fixes in a visual way. Jira’s extensive marketplace of apps is also a major benefit, helping to suit almost any need.
Cost: Jira’s pricing is based on the number of users, starting from $7.50 per user/month for the Standard plan and $14.50 per user/month for the Premium plan for small teams (up to 10 users). Larger teams need to get a quote for enterprise pricing.
Zoho Bug Tracker
Use as a Bug Reporting Tool: Zoho Bug Tracker allows for bug reporting with an easy-to-use interface that allows for the submission of bugs, assignment to team members, setting priorities, and tracking bugs through to resolution. It supports custom workflows and statuses to match your team’s processes.
Unique Features: Its simplicity and integration with the broader Zoho ecosystem, including Zoho Projects, make it a compelling choice for businesses already using other Zoho products. The ability to set up business rules for automatic actions on bug reports is another notable feature.
Cost: Zoho Bug Tracker is part of Zoho Projects. The pricing starts at $5 per user/month billed annually for the Premium plan and goes up to $10 for the Enterprise plan. There’s also a free version with limited features suitable for up to three users.
Bugzilla
Use as a Bug Reporting Tool: Bugzilla is an open-source tool that’s ideal for tracking bugs and issues. It provides the facility to create detailed submission forms, carry out advanced searching, and set up email notifications. Its flexibility is a key strength, with customizable fields and statuses to adapt to different project needs.
Unique Features: Being open-source, Bugzilla is highly customizable and free to use, making it ideal for companies with the technical know-how to set up and maintain the software. Its robust search capabilities and comprehensive reporting features are particularly noteworthy.
Cost: Free, being an open-source solution. However, hosting, maintenance, and any custom development will still incur costs, based on the resources used and chosen by the organization.
Atarim
Use as a Bug Reporting Tool: Atarim differs from traditional bug tracking tools by offering a visual feedback system directly on websites. Users can click anywhere on a site to leave comments, highlight issues, or suggest improvements, which are then automatically converted into tasks.
Unique Features: The visual feedback and ‘sticky note’ system make it incredibly user-friendly for non-technical stakeholders to report issues. Atarim’s integration into websites for direct feedback collection and the automated task creation from these reports streamline the web development workflow significantly.
Cost: Atarim offers several pricing tiers, starting from $20 per month for the Starter Dashboard, with more comprehensive plans available for larger teams and agencies.
Examples of Good vs. Bad Bug Reports
We’ve provided general examples of how bug reports can be either helpful, or unhelpful, some specific strategies we would recommend for either developers or end users to consider, and our shortlist of software tools that can help with tracking and resolving bugs.
But what does a good (or a bad) bug report actually look like? Here are two examples, one of each, that we hope illustrate what we’d consider representative of each.
Bad Bug Report Example
Title: Doesn’t work
Description: Tried to use the feature, and it crashed. Doesn’t work at all, very frustrating!
Why It’s Bad: This bug report lacks almost every piece of useful information. The title is vague, the description provides no context or details about what feature was used, how it was used, what exactly happened, or any specific error messages. There’s no information on the environment, steps to reproduce, or expected vs. actual results. It leaves developers with no clear starting point for investigation.
Good Bug Report Example
Title: Cart Update Failure – Items Not Added After Selection on Chrome 90 on macOS Big Sur
Description: When adding items to the shopping cart from the product detail page, the cart fails to update, and items appear not to be added. This issue was observed in Chrome 90 on macOS Big Sur.
Steps to Reproduce:
- Navigate to the product detail page for product XYZ.
- Click the “Add to Cart” button.
- Navigate to the shopping cart via the top navigation menu.
Expected Result:
- The cart should display the newly added item, including the quantity and price update.
Actual Result:
- The cart displays as empty, with no indication that the item was added.
Environment:
- Browser: Chrome Version 90.0.4430.93
- OS: macOS Big Sur Version 11.2.3
- Date/Time: April 20, 2021, ~3 PM CST
Attachments:
- [Screenshot of the empty cart after attempting to add an item.]
- [Console log capturing the error message: “TypeError: Cannot read property ‘update’ of undefined at ShoppingCart.updateCart (shoppingCart.js:85)”]
Why It’s Good: This report is specific, detailed, and structured. It provides a clear, descriptive title and includes comprehensive details such as the steps to reproduce the bug, expected and actual results, and the environment in which the bug was encountered. Attachments add huge value by providing visual proof and log data, helping developers to understand the problem fully and start working on a fix more efficiently.
It’s clear that the second bug report provides developers with a much more helpful starting point for replicating the bug and resolving it. It’s usually only by having all of the data needed to reproduce the error that it can become possible to identify what the cause may be, and then start to analyze how to fix it.
In essence, a good bug report, like the example above, should aim to do the following:
- Use descriptive titles that summarize the issue clearly and concisely.
- Provide a detailed description, including what was attempted and any specific error messages shown.
- Clearly outline the steps needed to reproduce the issue to make sure that the developers can see the bug for themselves.
- Distinguish between expected and actual results to clarify the nature of the problem.
- Include the environment details such as the type of device, operating system, browser version, etc., as any of these can significantly impact the bug’s reproducibility.
- Attach relevant files such as screenshots, logs, or videos, to provide additional context and evidence.
After Action Report: Integrate Bug Reporting – And Not As An Afterthought
We hope that, having read our advice and seen our examples, that it’s clear just how impactful a good bug report can be, and what the essential components are that make a bug report something that can help developers make a difference.
But it’s not just about the tools you use, or the structure used to frame the report. It’s about something else: empathy.
The best bug reports are the ones written with the developers in mind, and with an understanding of what they really need in order to resolve any issue the user has come across. Providing detailed information is crucial, certainly. But it’s also essential to think about how that information is presented, the logical order, and the steps needed to ensure the issue is replicable. When users put themselves in the shoes of the developers, and tailor the bug report accordingly, everyone wins in the end.
We like to think of it like this: effective bug reporting isn’t about pointing out what’s wrong – it’s about collaborating with the developers, and contributing to a solution. You may well not know how to fix it, but a good bug report is a starting point for a meaningful collaboration. This is especially true if there is a culture in which developers feel able to respond to users’ bug reports to clarify questions or points. This two-way communication turns bug reports into actionable insights, rather than dead ends.
And on the subject of collaboration…
With Atarim, you can use simple point-and-click collaboration to enable clients to point at what they’re referring to on any live web page, and immediately leave feedback, say what needs to be changed, and so much more.
If you want to receive feedback that makes sense, make it easier to collaborate with clients, and finish projects in days instead of weeks, sign up to Atarim today – with paid plans from just $20 per month.
- Integrated into the leading visual collaboration platform trusted by 13,000+ agencies (web dev, design, and beyond) worldwide.
- Supporting project delivery for 1,200,000+ of their clients and stakeholders.
- Deliver projects in days instead of weeks.
