from our blog

How to Write an Effective Bug Report - The Right Format

Posted by Simranjeet Singh

Web design and management, web development, Development

Communication is a connecting block between a project owner and the service provider. It goes without saying that the chances of getting your project done efficiently and on time increase when you communicate with the said team effectively. Communication in a project doesn’t end with the final delivery or launch of the product. It goes beyond that. Bug reporting is one stage that needs equal attention and detailing as the Project Requirement Document.

Why Writing a Bug Report is Important?

As a project manager or a product owner, you want bugs removed from your development project, don’t you? And, this is only possible when you say a lot more than ‘it’s not working’ or ‘Fix this’. Such plane statements just tell the developers that something’s wrong. What’s wrong is still a question. Without a concrete response from you, it would be like finding a needle in the haystack.

Detailed information from you about the bug takes the developers many steps close to eradicating the bug. The developers can easily and quickly find the bugs and remove them when they know where to look and what to look for.

As pointed out by Andreas Larsen on GitHub, An example of a good bug report goes like this...

Title

The cart icon doesn't update when adding items.

Steps to reproduce

  • Go to a product page e.g., https://helloskinshop.co.uk/products/cetraben-cream
  • See that the cart icon on the top right (desktop) shows X items.
  • Click "add to cart" button.

Current Behaviour

The cart icon still shows X items, but after reload it updates.

Expected Behaviour

The cart icon shows X+1 items immediately.

Relevant logs and/or screenshots (optional)

Other comments (optional)

We need to hit 88mph for the flux capacitor to work.

Reported by

Andreas

Here’s how the Bug Report format looks like – Suggested by Andreas Larsen

Title

A short descriptive title that is more than ‘it’s not working.’

Steps to reproduce

How did you face the issue? Which page did you open? What were you actually trying to do when you faced the issue?

Current Behaviour

How is the issue displayed? What actually happens but should not have happened?

Expected Behaviour

What should actually happen as per the plan?

Relevant logs and/or screenshots (optional)

If you can, take screenshots of the issues/bugs and attach them in this section.

Other comment (optional)

Any other input, ideas, comments, etc., on how to fix the bug.

While Andreas’s bug report format is decent, we care to look a step beyond to know other absolute necessary fields. We found that there is some more info required to know the bug.

Further fields to give out more details in a bug report:

Bug Number ID

This is to avoid any duplication. So, you are not mentioning the same bug again and again. That will be a waste of time for you and the developer as well. Keeping track of every bug you report keeps things streamlined.

Device

Write the device name and model you used to operate the software and found the bug. If you tested the software/product on multiple devices, mentioned the outcomes and device names of each.

Operating System Version

Was it Mac, Windows, Android, or Linux? Mention the Operating system and the version you used to operate the software.

The Product Version

Instead of writing ‘I used the latest version,' write the name of the build along with the date it was handed over to you to be clearer.

Priority

Is it something you need to be resolved urgently, or can this issue wait as other aspects are more important? If you found multiple bugs, arrange them priority wise. Bugs are reported this way to avoid miscommunication or confusion. This allows the developers to visualize the problem before they actually get their hands on it. Such reporting highlights the key points a developer needs to begin his part of the work. The developer may or may not have further questions depending on the complexity of the bug, but they are sure to resolve the issues if they have every required detail from you.

Note: Point out the issues, don’t comment on the developer’s skills. Remember, a bug report is written so we can eliminate the bugs. Personal attacks in bug reporting don’t go well in a long term professional relationship. Plus, it won’t do any good in getting the bug resolved. The quality and decorum of a bug report must be maintained. It is easy to write a bug report, but it is tough to write an effective one.

Simranjeet Singh

Written by Simranjeet Singh

Writer | HubSpot Certified Inbound Marketer and Content Marketer