How to write the perfect bug report

If you find a bug , you probably want it fixed as quickly as possible. Kick off the process in style by writing the perfect bug report…

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? The better your bug report, 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:

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.

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.

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.

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

Actual outcome: Login fails with “Incorrect Username” error message.

What’s the problem: This is confusing, because it led me to try with a different username, although it was the password that was entered incorrectly.

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

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

What’s the problem: This is a huge security risk; there’s a bug that fails to check for passwords, but still logs users in.

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.

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.

Related posts:

It was three weeks and some change before Christmas 2018 and I wasn’t feeling it. I’d just bought a house that needed a lot of updates and the move and endless remodeling projects had taken their…

What happens when you lose your sunshine? When your light no longer glows with the fluorescent hues of you, what happens to you? Do traumatic experiences really corrupt our mental? Are they that…

One of the many things that make sports more enjoyable is the rivalry between the teams. I mean at big games, the atmosphere is like nothing you’ve ever seen and always makes a lot of the games more…