A friend of mine was complaining tonight about how people don’t write good bug reports. A Google search for “how to write good bug reports” turned up some sensible advice on the subject, but mostly verbose and poorly-written.

The best advice I ever got about how to write good bug reports was from my former manager. We use a tool at work that other people write for us, so they aren’t users, and we aren’t programmers. We have to work at it to write explanations that make sense to them, and they don’t intuitively understand what we’re expecting to happen in all cases.

Her advice can be summed up in three short points:

1. Tell them what the problem behavior is.
2. Tell them what you did that led to the problem behavior.
3. Tell them what behavior you want instead.

#2 is extremely important. Be as specific as possible. Write it down in a series of numbered steps. In programmer-speak this is called “steps to reproduce”. This will make your programmer happy and also make sure that they don’t ignore you because they can’t see the same problem on their setup and can’t be sure how you created it on yours.

Personally, I was having the most trouble with #3, remembering not just to complain about the problem and assume they would know why it was a problem and what the solution was, but to explain exactly what I wanted instead, in detail. Trust me, the programmer doesn’t automatically know what you want. They’re hired to write code, not read minds.

Now go forth, and write good bug reports.

If your organization happens to use Bugzilla, this information (particularly about how to write a good summary) may also be helpful.