Contents
Text Link
Workflow tips

How to Write a Bug Report that Will Make Your Developers Happy

Contents

We explore the good, the bad and the ugly of bug reports. And share some tips and tricks on how to write actionable bug reports that will make your developers love you!

So, 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 homepage and another bug on the features page. Please fix.”

Both examples don’t help anyone, much less a developer. Based on this information, there’s no way to know what the problem is and the developer will need to spend a lot of 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.

  1. Title
  2. Summary
  3. Visual proof
  4. Expected vs. actual results
  5. Steps to reproduce
  6. Environment
  7. Console logs
  8. Source URL
  9. Severity and priority
  10. Optional

[Download your free ultimate bug report checklist - PDF]

Perhaps some items on the checklist items sound familiar, that is great! But if not, don't panic. We are 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 fourteen (!) free bug reporting template examples you can copy for your web testing process]

1. Title

Keep it short and specific.

Make sure it clearly summarises what the bug is and mentions the location or category. Having a clear title 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."

  • vague
  • aggressive
  • includes too many words
  • asks for a solution to be implemented

✅ Good: “CART - New items added to cart do not appear”

  • it helps the developers instantly locate the issue (CART)
  • 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 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: "On [DATE], I tried adding [PRODUCT] to the cart, nothing happened after clicking the 'add' button on product overview webpage."

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. So, that is also the same for 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 some 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! Always assume that your developer has no idea about the bug you found - how does he reproduce it?

As always, keep it simple!

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. This is especially important for developers. 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 logs 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. It saves them a bunch of time on any issue!

A lot of crashes or errors are hard to replicate, so having the logs can be super informative.

Pro tip: Marker.io adds the console logs automatically to every ticket you create. 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 navigate faster, which makes spotting the issue faster and saves everyone 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, your developer understands how quickly a bug 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
  • enhancement

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

  • high
  • medium
  • 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 (your own)
  • Assigned person (the developer, usually)
  • 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 stupid simple → Keep everything as straightforward as possible. 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.

[Download your free ultimate bug report checklist - PDF]

These insights were shared by the Marker.io team - helping you fight your bugs, one issue at a time. Take our visual bug tracker for a spin and let us know what you think!

Continue reading

Speed up website testing and collect client feedback!

Start free trial
Free 15-day trial  •  No credit card required •  Cancel anytime