In theory, the point of reporting a bug is to get it fixed, or at least to help. Too often I see (and receive) bug reports that are almost useless.

Writing a good bug report isn't hard, it just takes a little discipline, which can be assisted by a good bug tracking system.

Why report bugs?

In theory developers will only release a package that is in some sense fully tested; in practice this is almost impossible. The number of different possible test cases quickly makes exhaustive testing impractical. This means that there will always bugs.

To fix a bug, developers need to:

  • Know about it. If no-one knows about it, you bug will never be addressed (except by accident).
  • Understand it. What happened compared to what you expected.
  • Replicate it. If I can't make it happen, I can't tell if I've fixed it.

Some notes of caution

What you see as a bug might be something else.

  • Your lack of understanding
    I tried to think of a nicer way to put this with no success. Just because a result isn't what you wanted or expected doesn't make it "wrong". If your paying for the development you might have a specification against which to compare the result and/or have the right to change your mind, but tossing around phrases like "your program does the wrong thing" is going to create resistance. A developer is quite likely to spend some time dissecting your bug report to find mistakes in it rather than address the actual bug. The ensuing flame wars won't achieve much.
  • Expected behaviour poorly documented
    Documentation is hard to do well (ref to doc article) and often lags behind the application release. Documentation bugs are still bugs, but they sometimes get dealt with by different people. If you read the documentation say so (with references where appropriate); technical writers might be so astonished that anyone is actually looking at their work that your feedback will have more impact than you expect.
  • A configuration problem
    Especially for bugs of the "I can't edit ..." kind. Security settings and policies can change in the background without your knowledge and cause symptoms like this.
  • A problem elsewhere in your environment
    Your network, file servers, printers or some other piece of software may be failing, and you only see the symptoms in the 'buggy' application

Fault or blame isn't a useful concept in bug reporting.

Bug reporters (or victims if you prefer) should remember that the developers are not malevolent conspirators trying to ruin your life with deliberately defective software and refusing to help. Neither can they see what's on your screen, nor will they have the same version of 'normal' as you. "When I open the file it looks funny" doesn't say anything - open with what application, funny in what way (what do you see vs what did you expect).

Correspondingly, developers should remember that users are experts in their jobs, not yours. Other people's environments are subject to rules and restrictions that don't apply to you. "Just install {package}" isn't helpful to a user with no administration rights and invites the response "and how do I do that" from many more.

Good bug reporting

Context is everything; not all of these steps are appropriate for every situation and the specific actions may change, but the general process remains.

  1. Has it already been reported?
    If someone else has already reported the same problem, don't create a new bug - it's a waste of developer effort to determine that it's a duplicate. If you have a bug tracking mechanism, search first. If your tracking system allows you can add a 'me too' to the existing bug (more occurrences can move a bug up the priority list).
  2. Can you reproduce it?
    If you can't make it happen, then the developers probably can't either. Such bugs are unlikely to be addressed (bug trackers often support a status of 'Not reproducible' or similar. This doesn't mean it didn't happen, only that no-one can reasonably help.
  3. What are the minimum number of steps to reproduce it?
    Remembering that the developers aren't looking at your screen, make the problem as simple as possible to reproduce.
  4. What are the implications of the bug?
    Bugs get priorities - but your urgent problem isn't urgent to anyone else. Is it a cosmetic problem (wrong label, incorrect tab sequence), a specific function failing (can't print the xyz report) or a data validation/entry problem (can't save new clients, can't edit the 'business segment' field).
  5. How would you respond if you received this report?
    Read your bug report before you send it. You're not writing a novel, but try to get rid of the spelling errors and grotesque sentences. Be polite - you might be asking for help from a stranger who will gain no benefit; insults are not they best option.

Bug tracking

Bug tracking and resolution should be a standardised process, something like this:

Developers note those coloured arrows at the right; communicate with the user, let your users know what's happening - they won't always be happy, but bug reports that disappear into a black hole are extremely frustrating.

Bad bugs

Some bugs are elusive or otherwise difficult.

  • The legendary Loch Ness Bug is regularly reported by unreliable witnesses, but can never be found.
  • The truly frightening Angry Girlfriend Bug delays it's full effect - things look normal and all your inquiries report "Everythings fine" but you just know something's wrong.
  • The UFO bug survives repeated proof that it doesn't exist because some users insist that it's real.

(I don't claim credit for these - the internet is my friend)


There are lots of bug trackers; here are a couple:

Bugzilla bug tracker (used by Mozilla projects like Firefox and Thunderbird)

RT (Request Tracker)

And a Wikipedia article comparing features from different tracking systems

Some bug reporting methods in the wild:

Apple bug reporting form

Commodo Internet Security bug reporting guide