Gary Haran.com

Writing bug reports is not an art form but a science. If you write bug reports for your team (and yes programmers should write some) here is a short list of what your report should do.

1. Tile of a bug report: describe with a subject and a verb

The title should be a clear and concise explanation of the problem. It should include a subject and a verb.

Bad: Saving does not work.
Good: Body field does not save on submit.

Don’t limit yourself to only subject and verb when the problem only occurs in some circumstances.

Better: Body field does not save on submit when using IE 7.

2. Body of a bug report: enumerate steps to reproduce

The body of the bug report should explain what steps lead to the problem. This means that anyone reading the bug report should be able to reproduce it using only the information in the report.

Bad: [empty body]
Bad: Field body does not save.
Good: I logged on with user madcoco and typed in the usual lorem ipsum in the body field. When I hit submit the “saving” message appeared but timed-out. When I hit refresh the rest of the form was saved but not the body field. This occured using Internet Explorer 7 but worked fine in Firefox 3.

Don’t forget that as you get more information you can always append more text to the body.

Better: John Doe from SkyNet tells me that he has the same error and it seems to be related to the latest Windows Update from Microsoft. This is a known issue as seen on http://www.ie-vista.com/known_issues.html

3. Body of a bug report: support the report with screenshot or screencast

The best bug report I received was a 22 second screencast. It arrived via email from a user who used some code of mine but was really bad at English. A screenshot might be all it takes but a video is the ultimate bug report.

Happy bug squashing!