Bug reports that are helpful

Angry fists below keyboard and coffee bean filled cup

Why create helpful bug reports?

Part of being a productive developer is being able to distinguish between what the task requires and that little bit extra that could be fixed. Don’t fall down the rabbit hole. If you discover what you think is a bug, take a quick note in your notebook and come back. You can create a bug report.

Another developer on your team who needs a new story can pick it up and give the bug the attention that it deserves.

A little fix here and there can have other consequences, even if you have good tests. It’s better to come back at the end and make changes if they’re small and in their own commits.

When it’s a bug you’ve found, don’t show it to your project manager right away. Spend a little time yourself, looking into it and create a solid bug report.

The developer who does the work will appreciate the extra work on your part to explain exactly what’s wrong. It also means you aren’t distracted by the bug (unless it’s critical to your task/story) and it will still get fixed.

Writing helpful bug reports is an easy win that it makes everyone more productive.

The developer who receives the bug report will be able to fix it faster and more independently. This is because he/she won’t have to ask you to explain it. The project manager will be to understand the problem, prioritise it and be able to test to check that it’s fixed. This is because it explains the problem at a high level at the top and has the rest of the detail at the bottom.

Recommended book on bugs

“Debug It!” by Paul Butcher, I read it at a time when was spending a lot of time working through bugs. It took a weekend to read and I solved a bug that I had spent all week looking at in half a day. It includes a section on bug reports in Part II Chapter 6.1 Tracking Bugs.

Free bug report template:

Below is the template that I use to log bugs:

Steps to reproduce

  1. Log in as user x
  2. Click button y
  3. Type z and press search


  • See a list of users sorted alphabetically


  • List of users sorted by ID


  • Relevant log snippets/link to logs
  • Screenshots of how it looks / screenshot of network tab / the javascript console
  • Text from emails sent about the bug

Potential fix

  • Change SQL query to include a SORT filter in src/database/user-search.sql

Leave a Reply

Your email address will not be published. Required fields are marked *