How to write a good bug report


Here are 10 tips from Rex Black's "The Fine Art of Writing a Good Bug Report":

1. Structure. A tester who uses a deliberate, careful approach to testing, and takes careful notes, tends to have a good idea of what’s going on with the system under test. When failures occur, he knows when the first signs of failure
manifested themselves.

2. Reproduce. The tester should check reproducibility of a failure before writing a bug report. If the problem doesn’t recur, she should still write the bug report, but she must note the sporadic nature of the behavior. A good rule of
thumb is three attempts to recreate the failure before writing the report. Documenting a clean set of steps to reproduce the problem addresses the issue of reproducibility head-on.

3. Isolate. After reproducing the failure, the tester should then proceed to isolate the bug. This refers to changing certain variables, such as system configuration, that may alter the symptom of the failure. This information gives developers
a head start on debugging.

4. Generalize. After the tester has an isolated and reproducible case, he should try to generalize the problem. Does the same failure occur in other modules or locations? Can he find more severe occurrences of the same fault?

5. Compare. If a tester has previously verified the underlying test condition in the test case that found the bug, the tester should check these prior results to see if the condition passed in earlier runs. If so, then the bug is likely
a case of regression, where a once-working feature now fails. Note that test conditions often occur in more than one test case, so this step can involves more work than just checking past runs of the same test case. Also, if you have a reference platform,
repeat the test there and note result.

6. Summarize. The first line of the bug report, the failure summary, is the most critical. The tester should spend some time thinking through how the failure observed will affect the customer. This not only allows the tester to write a
bug report that hooks the reader and communicates clearly to management, but also helps with setting bug report priority.

7. Condense. With a first draft of the bug report written, the tester should reread it, focusing on eliminating extraneous steps or words. Cryptic commentary is, of course, not the goal, but the report should not wear out its welcome by
droning on endlessly about irrelevant details or steps which need not be performed to repeat the failure.

8. Disambiguate. In addition to eliminating wordiness, the tester should go through the report to make sure it is not subject to misinterpretation. Some words or phrases are vague, misleading, or subjective, and should be avoided. Clear,
indisputable statements of fact are the goal.

9. Neutralize. Being the bearer of bad news presents the tester with the challenge of delicate presentation. Bug reports should be fair-minded in their wording. Attacking individual developers, criticizing the underlying error, attempting
humor, or using sarcasm can create ill will with developers and divert attention from the bigger goal: increasing the quality of the product. The cautious tester confines her bug reports to statements of fact.

10. Review. Once the tester feels the bug report is the best one he can write, he should submit it to one or more test peers for a review. The reviewing peers should make suggestions, ask clarifying questions, and even, if appropriate,
challenge the tester’s assertion that the behavior is buggy. The test team should only submit the best possible bug report, given the time constraints appropriate to the priority of the bug.

There are some useful “good/better” examples of bug reports in http://www.rbcs-us.com/images/documents/Fine-Art-of-Writing-a-Good-Bug-Report-(Slides).pdf .