How to drive to work - aka how to file a good bug report

[Doom9]

It is perhaps the most frustrating thing ever for any programmer to be slapped with a "your program doesn't work". When you write software, you obviously take some time testing certain scenarios and wouldn't release something you know doesn't work, and if you know a feature doesn't work properly, you warn people about this upfront. Therefore, it is crucial that if you want your problem to be fixed, you make a good report that helps the people writing the software that failed on you, to correct whichever issue it is that you may be experiencing.

But before delving into details let's have a look at an example for the less tech savvy:

Suppose one morning you get out of your house, to your car and want to drive to work. But, you cannot start your car. Now you could call the shop right away , and they'd probably send someone over for good money (the more urgent it is the more it will cost obviously). Or you could think for a moment first. Do you still have any gas left in the tank? It's unlikely that you don't, but perhaps you've just barely managed to drive home last night and forgot to stop for gas. So, the money for the service technician would be ill spent if he just has to fill up your car, wouldn't you agree?
There are other quite obvious things: you picked the car key of your wife (first indication is probably that it doesn't fit, and if it fits you still can't turn it). There's no need to have somebody over for that either.
Or then there's the battery angle. Could it be that your battery doesn't have enough juice left? If you open the door and the light doesn't go on, if you try turning on the lights and they don't work, if you try the stereo and that doesn't work either.. it's a strong indicator. So, if that is it, if you call for a technician and tell him what care, make and model you have, he can make sure to not have to drive back to get the proper battery once he's figured out the battery was the problem.

Then we have what most people do - the casual "under the hood" glance. You may not know what you're looking for, but popping the hood and having a look to see if something is off, has never hurt anybody (unless you do it after driving and opening the valve of the radiator). Perhaps you see some loose cables? Perhaps you can even reconnect them because its obvious where they belong (battery cables, etc.). Or you might see some damage by a wild animal. Either way, if you see something is off and you cannot fix it, you can at least tell the people you're going to call about what you saw, thus perhaps giving them a clue what might be wrong and come prepared.

Or, you could call right away, and on top of having to pay be laughed at if your tank turns out to be empty or you picked the wrong key. You may not mind, but I'm pretty sure the next time you'll check for the obvious.. nobody likes paying to be laughed at (okay, if you go to a comedy club it might be different). And in case of the key mismatch, you might've solved the problem on your own, in a lot less time, and without any additional cost.

So, what do I want to say with that: even if you pay for support, to get your problem fixed in the shortest possible amount of time, it pays out to be informed and tell the people that come to help you as much as possible about your problem. It'll save you time and money.


Now turning back to software. You either pay for support (and usually you get very little) with the price of the software, or you have to get a support contract that costs extra. The software we're with here on this forum usually doesn't come with much of a support entitlement, and when it comes to free software, there is no support entitlement whatsoever and whomever decides to help you does so on his time, so provides a service for you at no cost for you, but cost for him (time).

It is therefore crucial that you make a significant effort to be as concise about any report you make and any question you may have as possible. If you encounter a problem, you need to go through the following steps:

1) can my problem be reproduced? That doesn't end with "doing the exact same thing again". Your problem might be dependant on the steps you take, the "material" you use, and even your computer. For instance if you use movie A and the problem happens, then use movie B and it does not, you must mention this as it points to a problem that only occurrs with a certain source. Or, if a software has always been working for you using certain settings, and now you're trying different settings, it is reasonable to assume that your settings have something to do with the problem and thus you must mention which settings you're using (and especially the difference to those that worked). It is also not unreasonable that you try to find out which setting change caused your problem. If you changed 3 things to get from a working to a nonworking state, start back in the working state, activate the first setting, try again, if it still works, activate the second setting, etc. That way when you report the problem you can point the finger at the offending option.

If you cannot reliably reproduce a problem, there is a very good chance that the problem lies somewhere between the chair, your PC, or the configuration of your PC and the software you're trying to blame and the people who wrote it are perfectly innocent.

2) try to pinpoint the problem
This starts with the above. Find a scenario that works, then gradually proceed to one that does not. Then describe the working and the non working scenario in great detail.

3) give important information about your setup
For instance program versions. If you use AviSynth, whether or not you use the stable 2.5.5 or the 2.5.6 betas might be very important. If the software requires a certain runtime (java or .net for instance), the version you're using might be important.

4) you can never give enough info
While from a problem solving standpoint, the info to really pinpoint a problem is normally not that much, you as a user will not know that. And so to prevent a lenghty pingpoing session in which you have to constantly give more info as you're being asked for, just try to give everything from the getgo. I realize this requires a certain extra effort and time, but that time is well spent as it normally permits others to more quickly solve your problem.

5) indicate what you have tried to solve the problem on your own
This is to ensure that the people trying to help you won't suggest you try something you've already tried.. this also helps others to help you more quickly.

6) Nobody owes you a (quick resolution) or a fix unless you've specifically paid for the solution. Anything else is goodwill..