We normally take the humble bug report for granted, but getting your company to write good bug reports is one of the cheapest and easiest ways you can increase product quality and shorten development schedules. That’s because, when a bug report is poorly worded or doesn’t include all the key information, it takes a lot longer to find and fix the problem being reported — and often it doesn’t get fixed at all.
Now, the precise guidelines for reporting defects vary by company and product. The information you need to include in a problem report for an Android app is very different from that needed for an in-police-car video recorder. And the way problems are reported varies too: Sometimes you’ll be filling out a detailed form as a part of your team’s formal defect tracking system, and other times you might be sending a quick email to a development manager.
But in all cases, certain general guidelines apply.
So, help out your development team and increase the odds that the problem you saw will be addressed by following these five easy steps to writing good bug reports!
- Report every defect you see. Don’t assume someone else has reported the problem unless you know there’s already a bug filed for it. Two days after we released a product, I once talked to a very angry sales guy at my company, who was irate that my team hadn’t addressed a problem he was seeing all the time. It turns out there was something special about his environment and he was the only person who had seen the problem in the pre-release code. But he didn’t file a bug report — he figured the QA team was responsible for that.
- Write a clear problem report. Please answer these three basic questions: What did you do? What happened? What did you expect to happen instead? (And don’t be cute: Writing that the application “bit the dust” is not particularly useful, even if it makes you feel better. Did it crash? Hang? Display a fatal error message?)
- Tell us about the environment. Often the environmental details matter: What build of the code are you using? What are the versions of the other key software components in the system? (This will be domain-specific, but for instance, I normally want to know the version of the device firmware, the operating system or the web browser; whatever is relevant to the product at hand.) If you’re hitting server APIs, is your client pointing at the production environment or a pre-release staging environment? And so on.
- Gather any log files. Again, this varies by product, but normally there is quite a lot of information that might be useful for debugging in a log file or core file, especially when we’re talking about pre-release products. So if possible, please save these diagnostic files aside as soon as you see the bug. The product I’m working on right now only keeps a two-hour-long log file because of storage space constraints. So if you forget to include the log file and then my team has to ask for it, it’s probably too late!
- See if you can reproduce the problem. After the problem happens once, save aside the log file, and then, if possible, push the car back up to the top of the hill and see if you can make it happen again. The bugs that are easiest to zap are the ones where the developer has a very clear path to reproducing the problem. I realize this isn’t always possible — especially if you’re in the middle of demonstrating some pre-release product to an important customer — but when it is possible, it can be tremendously useful.
Do you have any other hints? Pass them on in the comments!