How to write an effective bug report
Imagine you have commissioned some software for your business - lets say it's an e-commerce system for your bike shop. You have several employees who work at your bike shop who use the system as admin users, and then hundreds or thousands of customer users.
Your developer is great, but the system they produce is not entirely bug free software. In fact of course there's no such thing as bug free software. The best one can hope for is to build software that is well planned, with a good architecture, that easily accommodates changing business requirements, and has a good set of tests that cover all of the important use cases.
As soon as your software is launched into the wild, your users will start using it, and users will start breaking it (or trying to at least). At this point you need them to report issues they encounter, and provide the information to the developer to help them identify and fix the problem.
Lets take a step back for a moment and consider what a terrible, worst-case bug report from a user might look like:
The product detail page is broken.
Now this is quick for the user to write, but it provides next to zero useful information for the developer. How about if the user is at least trying to be a bit helpful:
The layout of the product detail page looks all weird for products in the bike saddles category.
There's a little more detail in here now - at least we know the problem is related to the page layout, and it's restricted to products in a certain category.
So what would the developer think of this kind of bug report? I can guarantee you that they would not be too pleased about it at all!
What is the real purpose of the bug report?
When you submit a bug report, your ultimate goal is to help the software get better. This means you intend your report to aid in the fixing of a defect, and ideally with minimum effort on your part and of course on the part of the developer.
When you submit a half-baked bug report, you do not provide the developer with the information they need to fix the problem efficiently.
What's worse, due to the lack of information it's likely the developer will have to read your report, and then enter into some back and forth messaging to gather the missing information.
If you were the developer, what would you rather tackle - a vague description of some problem that someone might have encountered, or a detailed description of the problem and steps needed to reproduce it?
A well constructed bug report is much more likely to be tackled by the developer, and the defect much more likely to be fixed in a timely manner. In short, better bug reports lead to better software at a lower cost.
So what should be in a bug report?
The key to a good bug report is context. The report should contain everything the developer needs to identify/isolate/reproduce the issue without coming back to you for more information. Every time there is a back and forth conversation it slows down the process of actually fixing the issue.
Now all software is different, and this means the information that you should provide may greatly differ from project to project. But for the sake of this example, lets stick with the bike shop e-commerce system (a web application), and run through some suitable information:
- WHERE is the problem?
The first thing a developer needs to do is see the issue for themselves. In the case of a web application, this generally means you need to point them to the exact page the problem is on. This means including a link to the exact page in question. If the problem does not immediately appear when viewing the page, state the exact steps required to reproduce it. - WHAT is the problem?
Spend a moment to actually describe the nature of the problem. Saying "it's broken" is not helpful. If it's a layout issue, say so, if it's a form validation problem, state as much. The more pertinent information here the better. - HOW should it be fixed?
If you are a stakeholder in the software project (for example an admin user), you may well know what the correct solution is. For example, if a button colour is wrong, don't just say it's wrong - if you know what the correct colour should be, tell the developer. This prevents them from going away and having to hunt down what the correct colour should be. All this time adds up, and they could be better spending their time on other things like building your next big feature. - Describe your environment
This is especially important with web applications. In order to use the application, you must access it through your web browser. There are many different web browsers out there, and many different versions. Additionally, you might be using a Mac or a PC. Give all this info to the developer - browser name (e.g. Chrome, Firefox), browser version (e.g. 84.2), operating system (e.g. Mac OS Sierra). - Additional information
Sometimes, even more information can be very valuable to the developer. For example, describe what you were doing before you encountered the issue (I don't mean making a coffee!). If the problem appeared after you viewed certain other pages, mention this. The aim is to eliminate the need for the developer to further query you about the issue.
One important final tip - if you are submitting via email, or an issue tracker or any other medium that has a subject line, please do spend a moment to construct a subject that concisely describes the issue. Imagine an inbox full of bug reports - the developer should be able to quickly read the subject line and understand roughly what the issue might be.
An example of a good bug report
So, to wrap up, lets come up with an example bug report that should have been submitted to the bike shop developer in the first place. We'll include all the relevant information (we hope) and aim for the defect to be fixed as soon as possible.
Email subject:
Page layout is wonky on bike saddles product detail pages
Email message:
Hello. I've noticed that the page layout is not correct on the product detail pages for bike saddles. For example on this page: https://acme-bikes.com/catalog/saddles/razor-52/detail
The right hand column that shows the current basket contents is wrapping underneath the new discounts promo. When it does this it is obscured and the user cannot see the add to basket button.
I think this is because the recommend a friend promo is in the wrong position and is too wide.
I'm using Firefox 89.0 on Windows, but I can see the same issue on Chrome as well (again on Windows). The issue does not seem to occur on my phone using Android Chrome.
If I am logged out, the problem is still there but the positioning is slightly different - maybe because the recommend a friend promo is not showing.
As you can see, this single report should be plenty for the developer to fix the issue without bothering you for more details. It might take a little more time for you to write, but it's a single message that is sent, and you don't have to deal with any follow-up questions - so in the long run you are likely to be actually saving time - both for you and the developer.
I hope these tips help you understand the importance of good bug reports, and perhaps improve your own software as it continues to be developed.