What to include in a bug report other than “it doesn’t work”

March 19, 2020

Let’s face it, bug management is everyone’s least favorite part of software development. Despite all our efforts on writing tests, there will always be bugs. It takes a village to diligently test and maintain software. And the better we are at writing bug reports, the easier developers can fix them.

Spotted a bug, now what?

While it’s tempting to slack a developer, saying something like “the button doesn’t work,” doing so only leads to an email thread longer than a CVS receipt. Meanwhile, the bug is still there and your developer is annoyed.

We want to share with you what constitutes an effective bug report. To streamline your bug tracking process, we also recommend centralizing reports with a bug tracker like Trello, Asana or Github.

Bug report checklist

A good bug report should present enough data for developers to zoom in on the problem.


Your title should be clear and concise so that others can quickly understand the issue and prioritize accordingly.

  • Bad: ‘Why is the app crashing!?’
  • Good: ‘Document page - app stopped responding after clicking on the save button’


An application can behave differently based on the environment used. Depending on the type of your application, it’s helpful to prepare a bug report template to specify what environment data should be included. The following information is typically required in a bug report for web applications.

  • Device: What type of device and which specific model?
  • OS: which version of the OS?
  • Browser: What type of browser, which version of the browser, which DOM element was selected?
  • Screen size

Steps to reproduce

Although fixing bugs is a part of software development, developers might see the task as extra work. If a bug is irreproducible, the report will likely be labeled as “can’t reproduce” or worse “won’t fix”.

It is critical that developers get to experience bugs first-hand. We recommend numbering the steps to reproduce the bug. For example,

  1. Go to Project page > Integration tab
  2. Click on add an integration > add Trello

What you expect to see

This is when you put yourself in the shoes of end-users and describe what should’ve happened.

What you saw instead

Here’s the actual result. Does something unexpected happen? Or does nothing happen at all?

Visual feedback

A picture is worth a thousand words. An annotated screenshot definitely helps developers understand the problem faster.

Simplifying bug reporting with Cereo

We believe this checklist makes bug reports concise and yet informative. That being said, not everyone has an army of quality assurance professionals to write good bug reports. That’s why we built Cereo. We make it easy for non-technical team members, stakeholders and even end-users to report bugs with sufficient information.

With Cereo, anyone can report bugs in your live websites. In each report, Cereo will automatically include critical information like screenshots and enriched browser data.

Give it a try and let us know what you think!

Tammy Chu

Written by Tammy Chu
who lives and works in Taipei building useful things.