Writing a good bug report

Have you ever reported a bug to a forum or mailing list, only to have developers pester you with dumb questions or, even worse, no one seems to be interested in helping you? Why do they keep asking you for more and more information? Aren't they interested in fixing bugs? Why won't anyone help you?

Being on the sending and receiving end of bug reports for years, I find that most developers take pride in their software and want to fix bugs but can't action bug reports unless they have at least the following information:

Software version

Quote the version string of the software. For Windows software, you can usually find the version string in the Help / About dialog. If you're using command-line software, check the on-line help for the required command-line option. For example, GnuWin32 utilities display their version string if you use the --version option.

Operating system configuration

If you're using Microsoft Windows, you can open a command console and type systeminfo. You'll see plenty of information about your computer, include hotfixes and hardware information. Some of the information may be private, so you decide how much you want to share when you write your report.

Input data

Sample files or parameters used to cause the problem.

Steps to reproduce the problem

Provide every step you took.

Expected results

What you think should have happened when you found the bug instead.

Often, users (and testers) balk at the thought of writing down every step or the expected results because they seem superfluous. "Don't developers know how their own software works?" you ask? Can't you just write, Stratoblaster feature doesn't work. Fix it! Problem is that unless you write down all the steps and what you think should happen, your bug will probably be ignored (if it's free – beer or libre – software) or developers can't figure out what you're going on about and write back asking for more information (if you're paying for support). Put yourself in the developers' shoes: how can they (1) figure how to reproduce the bug and (2) know if they have fixed it?

If you accept that you have to provide all the steps, then how much detail do you have to give? My rule is to imagine that I want to explain to a friend how to use a feature. For example in Firefox, let's pretend there's a bug moving a bookmark from one folder to another. Here's how I would write the steps and expected results of a bug report:

1. Select Bookmarks / Organize Bookmarks menu item. Firefox should open the Library dialog.
2. In the Library dialog, select the bookmark you want to move using your mouse pointer.
3. Click and drag the bookmark to the destination folder.
4. Release the bookmark. BUG: Bookmark remains in original folder. EXPECTED: Bookmark is moved to destination folder.

Happy bug reporting!