How to write a proper bug report

Published by on October 23, 2014.
How to file a proper bug report in software development

Imagine coming home from a day at work, and there’s a note from your spouse that reads:

“Fix the light, it’s broken”

You have no idea where to start. Which light is it? Did they mean lamp? Which part is broken? How did it break? Is it outdoors or indoors?

When your spouse returns home, they ask, “How come you didn’t fix the light? Didn’t you see my note?”

Now think about how the developers on your team feel when they get a bug ticket that reads like this:

“The buttons on the homepage are broken”

I’m embarrassed to say, this is an actual bug report I filed recently. I didn’t describe how it could be reproduced nor in what context I’d found the bug. Needless to say, the developer who’d been assigned the ticket had no idea where to start. Truthfully, it even took me a while to remember what this bug was about!

This has probably happened to all of us at one point. We’re in a rush, we create a ticket (meaning to add more detail later), and then forget about it.

But if your team wants to ship software faster, you’re going to need to develop good habits. One of the most important: filing proper bug reports.

Here’s a good tactic we came up with at Sprintly. To start, if you’re not already using Text Expander, get yourself a copy. This will allow you to create keyboard shortcuts that will auto-expand text snippets.

For example, when I type in QLbug it auto-expands this text:

As a ___ I did ___ and expected ___ but experienced ___.

Steps to reproduce:


URL where bug was observed:


Environment: Local, Staging or Production

Logged in? [Yes / No]

Logged in as:

Customer contact:


This is a template I can use every time I file a bug. (We have something similar for Pull Requests.) It’s helping me build a habit of creating detailed bug reports that anyone could read.

What about your team? How do you ensure that tickets are properly filed? What’s the worst bug report you’ve seen? Leave us a comment below.