How to Write a Bug Report

Posted Tuesday, March 15, 2022 by Sri.Tagged CONCEPT, BEST PRACTICES
EDIT STATUS:first draft

There are only three elements in a good bug report:

  1. what you expected to see / tried to do
  2. what you saw instead (w/ screenshots)
  3. detailed steps to reproduce the bug

Additionally, you can provide:

  1. a workaround you found to get around the bug
  2. how critical the bug is to your workflow

It is most important to provide (3) detailed steps to reproduce the bug. Secondarily, the screen shot of the bug (camera phone pic is OK too) along with any error messages seen.

If you want to be an excellent bug reporter, you just need to stick to the first three items. It is enough to provide the steps to reproduce the bug and describe what you expected to happen instead.

Bug Reporting Failures

  1. Describing the bug without providing any other information - Telling us "there is a bug in the program" without any information doesn't help. You are the only one who can tell us where it is.

  2. Not capturing visual evidence of the bug - Share a screenshot with us, so when you describe the bug we can see what you are talking about. If there are any error messages, copy the complete error text because it contains information that you may not understand but will save us considerable time. Use your camera phone to take a snapshot. Don't summarize or paraphrase. Capture as much as the output as you can, because what you think is the important error might not be the source of it.

  3. Not providing specific steps to reproduce the bug - Provide the name of the app, the files you loaded, the buttons you pressed to get to the error state, the webpage link or screen dialog. Confirm that these steps work before you send them.

  4. Adding unnecessary detail unrelated to the bug - If you provide information that's NOT STRICTLY RELEVNT to reproducing the bug, KEEP IT SEPARATE from the bug report itself. That way, we don't end up trying to relate that information to the debugging context as we try to understand the report.

  5. Armchair speculating about causes of the bug - Even if you are an experienced programmer, keep this speculation to yourself. Don't put it in the bug report. Unless you are actively in the code solving the problem based on the steps you followed to reproduce the bug and see it happening on your test system, it is best to provide the steps to reproduce the bug and describe what you expected to happen instead.