Writing Good Bug Reports


I just came across this good article about writing good bug reports, so I thought I’d share.

The article is somewhat specific to writing bug reports to Apple, but still, there are many good concepts there. Here are some nuggets that stood out for me:

File one report per issue

Don’t try to save time by writing multiple problems into one radar/ticket. One issue should always be one ticket. This makes it much easier to track the status and to move it to people internally.

Make a short, runnable sample

Even if it’s trivial to reproduce. Delete everything that’s not important. Strip it down to just the bug.

Make it really obvious to trigger the issue

If possible, add a big button named “Press me to crash” or “Tap for tears.” Make it obvious.

Be concise

Don’t write a novel. Try to explain the issue in concise terms and then optionally add a second block where you go into more details. What have you tried already to work around it? What assumptions do you have?

The report title is especially important. Be clear and succinct. It should be descriptive. See it as an advertisement for your cause. There will always be too many bugs to fix. If you want your problem to be fixed, make an effort, and write up a good article. Write it so that the engineer wants to open it, read it, and fix it.

Keep in mind that the engineers might not have an efficient way to contact you. If they respond to a radar, this might be screened. And because screening can take up to a few days, try to write complete information that allows any engineer to reproduce the issue without further questions.