How to make really good bug reports

One of the best ways to help a developer improve their software is to report bugs. But of course there’s an art to bug reporting.

Most of the bug reports I get for NetNewsWire are very good. But now and again I get a report that isn’t that helpful, and I have to ask a bunch of questions before I understand it.

Here’s a made-up example:

“I subscribed to the The Cool Foo Bar feed, and it doesn’t display correctly.”

That immediately brings up a bunch of questions. The biggest one is: what’s the URL of the feed? Without the URL, I can’t possible reproduce the bug. If I can’t reproduce the bug, I can’t fix it.

More questions: does the feed validate? What view are you using (Combined View or traditional view)? What about the display is incorrect? What version of NetNewsWire are you using? What version of OS X are you using?

When I worked at UserLand we used to suggest a format for reporting bugs. It’s a good format, and I recommend it to anyone reporting bugs to anybody. The format:

1. What I did. This should include as much detail as possible.

2. What I expected.

3. What actually happened.

Knowing what was expected is important information. Sometimes bugs aren’t bugs but are misunderstandings. Sometimes the app is working as designed, but really it should work as the user expects. But most of the time a bug report describes an actual bug.

Another thing: if applicable, include a screen shot as part of #3. This doesn’t make sense for some types of bugs, but for display bugs it’s hugely valuable.

Now, as I said, most of the bug reports we get are quite good. So this is just for people who’d like to make their bug reports more useful.