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.
The better your bug report, the quicker the problem can get solved.
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:
A good summary / title
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.
A couple of examples
Example 1
- Go to example.com/myprofile
- Enter username in login field
- Enter incorrect password in password field
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.
Example 2
- Go to example.com/myprofile
- Enter username in login field
- Enter incorrect password in password field
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.
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.
Haje is a pitch coach based in Silicon Valley, working with a founders all over the world to create the right starting point for productive conversations with investors — from a compelling narrative to a perfect pitch. You can find out more at Haje.me. You can also find Haje on Twitter and LinkedIn.
