How To Report a Software Bug (or any other Problem)

Reporting a bug in software is no different than reporting any other problem you want addressed: the more specific you are, the better and quicker service you’re likely to get.

1. Always assume that the person responsible for the problem you want fixed is just as interested as you are in fixing it. If you’re working with good people, that’s usually the case.
2. Always assume that good people have 1000 things to do, but will still prioritize your issue higher if they think they can take care of it quickly.
3. Scientifically-minded problem-solvers determine whether a problem can be solved by coming up with hypotheses and testing them.
4. Reproducibility is key: very few problems can be solved by just thinking about how the problem could have arisen and implementing a solution. Even given such a solution, it is highly untestable (how can you verify that you’ve fixed a problem that you can’t even reproduce?). Instructions for quickly—or, at the very least, reliably—reproducing the problem are paramount.
5. Therefore, if your report includes the information a problem-solver needs in order to reproduce the problem, form a hypothesis and test it quickly, it stands a much better chance of getting addressed quickly.
6. Even if you do all of this, it does not necessarily mean that your problem will be solved quickly, but it means that you’ll find out much more quickly whether or not you’ve got a tough issue on your hands. You may have to wait for a solution, but at least you know you’re not waiting two weeks for someone to even look at your problem.
7. Lying about the severity of the problem is not a good way to increase the priority of your issue, especially if you’re not providing enough information. For example, reporting that “NOTHING’S WORKING!!!” when you have, in fact, discovered a typo or a broken link is unlikely to inspire a reaction more than once or twice. Bad reputations are hard to un-earn.

You probably wouldn’t be surprised at all to find how long it takes to train people to make good bug reports. We have one client to whom we send punishing support invoices every month because only one of their employees knows how to provide information from which we can even attempt to reproduce a problem. It’s a shame because many problems that look intractable in the absence of a good bug report are solved quite easily and quickly once that information is finally made available (usually by twisting some arms).