The fine art of writing a good bug report. Ten tips that turn sloppy notes into a document developers will act on.

Structure — test carefully

Good bug reports rest on structured testing. If the underlying testing is sloppy — no written test cases, no notes, no process — the report will be sloppy too. Bug reporting begins the moment expected and observed results diverge, which means you need to know the expected result in writing before you run the test.

• Use a deliberate, documented approach to testing.
• Follow written test cases, or run automated ones against written procedures.
• Take notes as you go. The note is the raw material of the report.

Reproduce — test it again

Always verify the failure is reproducible as part of writing the report. Three tries is a reasonable rule of thumb. Document a crisp sequence of actions that reproduces the failure, and state the incidence rate openly if the failure is intermittent. Clean steps to reproduce head off the "cannot reproduce" bounce before it starts.

Isolate — test it differently

Change one variable at a time and watch whether the symptom changes. Isolation takes thought and an understanding of the system under test, and it can be as much work as the original test run. Match effort to severity. The goal is not to debug — the goal is to give the developer a head start by eliminating the obvious dead ends.

Generalize — test it elsewhere

Look for related failures. Does the same bug show up in other modules, with other data, on other platforms? Are there more severe occurrences of the same fault? Generalizing reduces duplicate reports, and it often reveals that the real bug is two layers down from the symptom you first caught.

Compare — review results of similar tests

Check whether the failure is a regression. Did the same test pass against an earlier build? On which build did it start failing? Not always possible — the feature may be new, or the earlier build may be impractical to reinstall — but when you can answer "new to build X," you have just cut the developer's search space in half.

Summarize — relate the test to the customer

Put a short, bumper-sticker summary on every report. Capture the failure and its impact on the customer in one line. Harder than it looks: testers need to spend real time on this sentence. A good summary gets management attention, names the bug for developers, and helps priority sort itself out without a meeting.

Condense — trim unnecessary information

Reread the report and cut extraneous words or steps. Everyone's time is precious. Don't waste any of it on verbiage — and don't cut any meat either. Cryptic one-liners are as bad as droning on. The target is clear prose at minimum length.

Disambiguate — use clear words

Remove, rephrase, or expand vague, misleading, or subjective statements. The goal is clear, indisputable statements of fact that cannot be misread. Lead the developer by the hand to the bug. "Trashed the text" is rhetoric. "Converted all text to control characters, numbers, and apparently random binary data" is a statement of fact.

Neutralize — express the problem impartially

Deliver bad news gently. Be fair-minded in wording and implications. Do not attack developers, do not criticize the underlying error, do not try to be funny, do not use sarcasm. Confine the report to statements of fact. You never know who will read it — executives, auditors, customers, lawyers. Write for that audience every time.

Review — be sure

Every tester should submit each bug report to one or more peers for a review. Reviewers make suggestions, ask clarifying questions, and challenge whether the thing really is a bug when that's warranted. The test team should only submit the best possible report, given the time budget appropriate to the bug's priority.