Submitting a Bug: Howto

Let's face it, occasionally software has bugs. Software can have bugs ranging from a mispelled word in the User Interface to an issue that causes a complete system crash and a minor rip in the space time continuum. None of these are good. Of course, in order to fix these bugs, the developers need certain information that only you – as the finder of the bug – can provide. The most useless thing in the world you can tell a developer is “Page X doesn't work, fix it!”

Step 1: When you attempt to do X and instead Y happens, double check what you've done. Did you type the command or values correctly? Did you click the right buttons? Did you follow the right steps? Regardless of what you think, try it again. Even if you did it correctly, the developer will need to know if it happens every time or just at 7:02 am EST on Mondays in July. Included in this one is telling us about your browser, some basic information on your settings, etc.

Step 2: Screenshots are king. Sure, you can tell me “this information is X and it should display Y!” or “I'm getting an error!” but if you give me a screenshot, there's no question about it and I don't have to ask you about it later. Face it, if you don't give us enough information, we're going to ask anyway. Besides, having a picture proves that you're not crazy and that it actually happened. 😉 The quick and easy way to do this is to hit Control-Print Screen*, paste the image into MS Paint, and save it as an image. Please don't paste it into a Word document, with the number of exploits and problems with VBA macros, many developers simply don't open them. If you really want to be helpful, select a color (red!), grab the spraypaint tool and circle the region where the error occurs.
* Print Screen is one of those buttons that you thought was useless normally just above or to the right of your Backspace key. Turns out it's not.

Step 3: Alright, now we how to make it break (Step 1) and what it looks like when it's broken (Step 2), but now we need to know what it was supposed to do. If you expected X, Y, and Z to happen, explain it. If you expected nothing to happen (think of hitting Cancel after hitting Edit), then say it. It turns out that it might not be a bug in the software, but a bug in the requirements. Let's stop a second and look at this. If you received a requirement like this:

With the inputs of 2 and 2, the output should be 4.

How would we get the result? Easy, multiply them! Oh wait, some of you said “Easy, add them!” Well, from this requirement alone, we don't have enough to determine which of us is right. We need more information. An cynic… er… experienced developer will notice these ambiguities and work to resolve them at the beginning. A new or crazy-busy developer won't even think twice about it and implement the first thing they imagine. The nasty thing here is that the code does exactly what it was supposed to and will compile, parse, whatever without any problems.

Step 4: Provide some context. If you've seen this issue somewhere else, mention it. Despite this being a bad developer habit, it's entirely possible that erroneous code was copied and pasted into multiple places or alternatively, multiple developers wrote similar functionality from different perspectives. In the intervening time, some of it was fixed and some wasn't, some handles more cases than the other, some handles errors gracefully, some doesn't. Now we have the similar problems appearing in multiple places causing everyone headaches.

So why would anyone want to do all of this? The most obvious reason is that with better information, it's much easier and faster for developers to track down the problem. I have yet to hear a developer say “Wow, this user sent me more information that I needed!”