How to write a bug report that will make your developers happy

You’ve just told your developer team that you found a bug and instantly get the reply: I need more information.

Before you know it, you’ve got an email thread a million miles long, your developer is fuming and the dreaded bug is still there.

Developers are often under a ton of pressure to solve issues quickly without actually having a lot of time on their hands.

They usually face two extremes: too much unhelpful information or too little important information.

“The website doesn’t work.”

or...

“I found a bug on the home and another bug on the features page. Please fix.”

Both examples don’t help anyone, much less a developer. From this feedback, there’s no way to know what the problem is and the developer will need to spend a lot more time investigating.

In short, while finding a bug can be helpful, how you document it is incredibly important.

In this post, we’re going to explore the good, the bad and the ugly of bug reports. And we’ll share some tips and tricks on how to write actionable bug reports that will make your developers love you.

What's in the perfect bug report?

Let's zoom in on what makes a good bug report and some of the other things to keep in mind to share actionable feedback. To do this, we highly recommend using a bug tracker like Trello, Jira, Asana, GitHub or GitLab and implementing a consistent, standardized approach.

The master checklist: everything you need to consider

After lots of personal experience (trial and error - ouch), research and talking it over with our developers, we came up with a checklist of ten essential points to consider.

Title
Summary
Visual proof
Expected vs. actual results
Steps to reproduce
Environment
Console logs
Source URL
Severity and priority
Optional

[Download your free ultimate bug report checklist - PDF]

Perhaps some of the checklist items sound familiar, but if not, don't panic. We're going to walk you through each step. Below you'll find a detailed breakdown of what each item means, plus relevant examples and visuals to help paint a clearer picture.

[Looking for a good bug report sample? Check out our nine free bug reporting template examples you can copy for your web testing process]

1. Title

Keep it short and specific. Make sure it clearly summarizes what the bug is and mentions the location or category. Having a clear name or ID on your report makes it easier for the developer to find later on and merge any duplicates.

❌ Bad: "I can't see the product when I add it, for some reason I try and it doesn't. WHY? Fix it asap."

This example is bad because it’s: vague, aggressive, includes too many words and asks for a solution to be implemented.

This is a better example:
✅ Good: “CART - New items added to cart do not appear”

This example is much better as it helps the developers instantly locate the issue (CART) and it focuses on the actual technical problem. When developers review it, they’ll be able to instantly assess the issue and decide to explore it by looking at the other elements of the bug report.

Here’s another set of bad and good example highlighting the points made above.

❌ Bad: "The text on the pricing page looks weird"
✅ Good: "PRICING - Headline text font size is incorrect"

2. Summary

If your title isn’t enough, you can add a short defect report summary. And we mean short. In as few words as possible, include when and how the bug occurred. As mentioned previously, your title and description may be used in searches, so make sure you include important keywords.

❌ Bad: "The other day I was trying add stuff to test and nothing showed up when I did that or clicked on the button."

✅ Good: "Tuesday morning, I was testing purchases from the product overview webpage and tried adding product XYZ to the cart, but nothing happened when I clicked on the 'add' button."

❌ Bad: The design text on the pricing page looks super weird and doesn't seem right. It shouldn't look that big and should be in a different color.

✅ Good: The headline text size and color on the pricing page don't match the original designs.

3. Visual proof

We all know that a picture is worth a thousand words, well, that can also be true in bug reporting. While it may not tell the whole story, a screenshot or video can add a lot of value by getting your developers to see and understand the problem faster.
Example

Pro tip: If you use Marker.io, you can even add visual annotations.

4. Expected vs. actual results

Now take the time to explain to your developer what you expected to happen (sometimes this is referred to as the user story) and what actually happened.

Example
Expected result: Item should be added to the cart when I click 'add'
Actual result: Item does not appear in the cart

5. Steps to reproduce

Here is your opportunity to share the steps needed to recreate the bug. Assume that your developer has no idea about the bug you found - how does he reproduce it?

The steps to follow should be comprehensive, easy to understand and short. The most important goal of this step is for your developer to experience the bug first-hand.

Example
Step 1: Search for product XYZ
Step 2: Click on product XYZ in search results
Step 3: Click on 'add to cart' button
Step 4: Go to cart

Pro tip:

Use a numbered list to explain the steps
If you’ve already managed to recreate the issue several times, you can include the reproducibility rate (example: 12/12 times bug reproduced).

6. Environment

Websites and apps can behave very differently depending on the environment used. It’s critical that the following information be included in any report your share:

Browser
Operating Systems (OS) and version
Screen size
Zoom level
Pixel ratio

*Pro tips: *

Marker.io will automatically collect this technical information.
Use BrowserStack with Marker.io to automatically grab virtual device information and capture cross-browser issues
Additional info that can be helpful: device type, network connectivity, battery state.

7. Console logs

These are where a developer can see all the errors that occur on a given webpage. Logs are also a place where developers can include info that will help them track certain user actions.

In general, including console logs can be valuable for developers as they can help them dig deeper and identify the root of the problem. A lot of crashes or errors are hard to replicate, so having the logs can be super informative.
Learn how to access your console logs in our Help Center.

8. Source URL

One important, but easy-to-forget item is the source URL. This will help the developers spot the issue and save a lot of time!

Pro tip: If you use Marker.io, we’ll automatically include this

9. Severity and priority

By defining the severity or priority of the issue, you can help your developer understand how quickly a bug you report should be fixed.

The severity of your bug can be defined by the level of impact it has on your website or product. Once this has been determined you can label it as: critical, major, minor, trivial, or enhancement.

The priority helps your developer determine which bug they should investigate and fix first. Here you can choose between: high, medium and low.

As the bug reporter, you will normally be responsible for identifying the severity and priority. However, as team work makes the dream work, don't forget to confirm the decision with your team.

10. Advanced information

Whether you're looking to write the most informative bug report ever or you're looking to score brownie points with your developer, you can also opt to include the following:

Reporter name
Assigned person
Due date

[How can Trello's Customer Fields make you awesome at bug reporting? Learn all the latest here]

Tips and tricks

In general, it's good to keep these basic guidelines in mind:

One bug = one issue Don't include multiple bugs in same issue
Avoid duplicates Always try to search your current issue tracker for existing reports
Reproduce the bug before creating the report This makes it more likely that the developer will be able to reproduce the problem and identify where it comes from
Don't forget to KISS: keep it simple, stupid Keep everything clear and focused on the problem, solution or idea at hand Using bullet points or numbered lists can help
Use a professional bug tracker This will help you keep everything in one place and avoid losing files and bug reports
Be kind Developers are people too and bugs happen - they’re part of the process in making great end products and websites

Save a developer, write a good bug report

It goes without saying that if you can master the art of a good bug report and issue tracking system, you’ll save more than just time and money - you’ll save your developer’s sanity.

Now that we've given you the right tools, it's time to use them. No more tornado of a million emails, screenshots and embarrassing screaming matches that send you running for the hills.

It's just you, and your new weapons: an awesome bug report and a solid bug tracking system.

Putting your new skills into action and implementing these key changes will no doubt send you developer’s happiness skyrocketing.

Never underestimate the power of a good bug report.