I just came across three nice articles on bug reports, how they are filed by customers, and what all customers (including programmers who are customers of others) can do to increase the likelihood of their bug being addressed. Luckily, I generally get good bug reports, and when they aren’t, it’s usually my fault (e.g. I currently get crash reports for the Moose, but I have no way to let users tell me what they were doing at the time, or to specify their e-mail address so I can ask them for more info). Anyway, on to the articles:
- Pistols at Dawn or How Not to Request a Feature – From the Rogue Amoeba guys. It delves into what actually goes on behind the scenes when you report a bug. Nice for programmers to see that others don’t work that differently, and nice for users to get a peek how programmers work.
- How to manipulate me (or, Tuesday Whipper-Snapping) – From Brent Simmons, whon concentrates more on the numbers game and the psychology of your wording.
- Useless, absurd, must, need, appalled, just, infuriating, essential, etc. – By Matt Linderman of 37Signals. It’s mostly a sample of bad reports (which aren’t very insightful if you’re not familiar with the products), but at the end he has one of his own reports as an example of how to do it right.
- Easy Programming a tangent to the topic by Daniel Jalkut (via Brent Simmons, developer of the best web browser RSS Newsreader out there)
Most of these articles also have great comments. The Executive summary of them all would probably be: Remember to state your problem that you’re trying to solve, not just how you’d change the program to solve it. The programmer might just be able to surprise you and solve your problem with a much better solution.
Also, make sure your bug report covers the following three points in detail:
- What you did. In the form of actual menu item choices and what button was clicked, e.g. “Double-clicked my image file’s icon in Finder”, not as a short summary like “I opened a file”. However, do also include an additional higher-level summary of what you were trying to do, like “I created a PDF image and wanted to put it on the web. For this I wanted to run it through Frobnitz to defrobnicate the file prior to uploading it.”
- What happened. In detail. Not “it didn’t work” or “it disappeared”, but rather “the application Frobnitz’s windows disappeared from the dock and a window showed up ‘the application Frobnitz unexpectedly crashed…'”. And always try to quote error messages verbatim. Sometimes a program has several error messages that differ in one word only, and if the programmer knows the exact text, they can find the spot in their code where it actually crashed.
- What you expected to happen instead.
Update: Added a link to Daniel Jalkut’s entry on the topic.