Bug Reporting 101: Saving a ton of time by getting it right

There are a thousand wrong ways of reporting a bug. Using the right way means fast response, good communications, and happy customers!


In our day-to-day lives, we rather frequently run into situations where something doesn’t work — whether it’s your car, a piece of software, or your boiler at home. Reporting an error is often a haphazard affair — but if you’re working in any industry, you can make the process a lot more effective if you create a well-crafted bug report.

So… How? It’s actually not very hard, and there’s some simple rules you can follow to make the techies’ jobs as easy as possible. Why would you bother making their lives easier? Well, it’s not because they’re lazy (although some are, I’m sure), but because the easier you make it, the quicker the problem can get solved.

Remember that a good bug report does one thing: It enables an engineer to understand why something is a problem, and then ideally gives them enough information to be able to reproduce the problem on their own system.

A good bug report has the following:

A good summary

Think of this as a headline that can be used to refer to this specific bug. “Problem on website” is a dreadful summary. “Login fails with a 500 error message on check-out page in Firefox, but works in Safari” is great.

Try to strike the perfect balance between brevity and information.

Background information

This is like a pre-amble, explaining the background of what you are doing.

If it’s a bug on a website, a typical condition might be what web browser and operating system you are using.

If it’s a mobile app, you’ll need to know what version of the app and operating system you have, etc.

If you’re reporting a problem with your boiler, the make and model of the boiler, along with when it was installed and by whom, is all great background information.

Steps to reproduce & ‘why this is a problem’

Then comes the description of the problem itself.

Don’t leap straight to the problem, explain how you got there, and what results you expected. The latter is especially important, because what you consider a bug may instead be a clumsily implemented piece of functionality, rather than an actual bug. To you it doesn’t make much of a difference, of course, but it does make a huge difference to how a particular bug is handled by the tech teams.

It is also worth mentioning why the problem is a problem, if relevant, as it can help decide how serious a bug is, how urgently it needs to be resolved, or help contextualise the situation where something might be a problem.

One example of steps-to-reproduce for a clumsy implementation could be:

1) Go to example.com/myprofile 2) Enter username in login field 3) Enter incorrect password in password field

Expected outcome: 4) Login fails with error message: “incorrect user name or password”

Actual outcome: 4) Login fails with “Incorrect Username” error message. This is confusing, because it led me to try with a different username, although it was the password that was entered incorrectly.

An example of a steps-to-reproduce for a critical bug might be:

1) Go to example.com/myprofile 2) Enter username in login field 3) Enter incorrect password in password field

Expected outcome: 4) Login fails with error message about “incorrect user name or password”

Actual outcome: 4) Login succeeds, and takes me to my profile page, giving me access to the editing tools.

In this particular case, it’s obviously a huge security risk; there’s a bug that fails to check for passwords, but still logs users in.

Repeatability

If you can make a bug happen, try to make it happen again. If a problem is intermittent, it’s crucial to mention this under the ‘Repeatability’ header — because otherwise, a developer is likely to reject the bug as ‘cannot be reproduced’, and it may be assumed that it was a bug that resolved itself somehow.

If your bug only happens every third time you try something, this is still relevant information. Make a habit of adding a note on how easy it is to reproduce the bug, even if it happens to you every single time.

Additional resources

It’s often helpful to include a link (if relevant) or a screen shot (if possible) with a bug report — you’d be amazed how often a screen shot shows something that is relevant, or that may help a developer figure out what is going on.


Scffld is a blog where Haje Jan Kamps covers the great, the terrible, and a sprinkling of best practices of customer service. There’s a bit more background here.

Show your support

Clapping shows how much you appreciated Haje Jan Kamps’s story.