How to Write a Bug Report
A dozen helpful tips
Copyright © 1997, Bernie Berger. All rights reserved.
1. Be very specific when describing the bug. Don’t let there be any room for interpretation. More concise means less ambiguous, so less clarification will be needed later on.
2. Calling windows by their correct names (by the name displayed on the title bar) will eliminate some ambiguity.
3. Don’t be repetitive. Don’t repeat yourself. Also, don’t say things twice or three times.
4. Try to limit the number of steps to recreate the problem. A bug that is written with 7 or more steps can usually become hard to read. It is usually possible to shorten that list.
5. Start describing with where the bug begins, not before. For example, you don't have to describe how to load and launch the application if the application crashes on exit.
6. Proofreading the bug report is very important. Send it through a spell checker before submitting it.
7. Make sure that all step numbers are sequenced. (No missing step numbers and no duplicates.)
8. Please make sure that you use sentences. This is a sentence. This not sentence.
9. Don’t use a condescending or negative tone in your bug reports. Don’t say things like "It's still broken", or “It is completely wrong”.
10. Don’t use vague terms like “It doesn’t work” or “not working properly”
11. If there is an error message involved, be sure to include the exact wording of the text in the bug report. If there is a GPF (General Protection Fault) be sure to include the name of the module and address of the crash.
12. Once the text of the report is entered, you don’t know whose eyes will see it. You might think that it will go to your manager and the developer and that’s it, but it could show up in other documents that you are not aware of, such as reports to senior management or clients, to the company intranet, to future test scripts or test plans. The point is that the bug report is your work product, and you should take pride in your work.