Guidelines for creating effective Problem Reports

Here are some helpful hints while you are filling out a problem report (locally IssueTrak).

  • Time - Note the time that you noticed the problem, and the exact time when it started / ended if you can extract those from the logs. Even though escaping from the problem may be more urgent than filling out the problem report form, it is important to keep notes about the time as you go along.

  • Description - Give a coherent description of the symptoms of the problem. The more clearly you can explain the problem, the more rapidly the support folks are likely to understand and solve your problem.

  • Exact Error Message - Quote the exact wording of any relevant error message you saw at the time, or which you can extract from the logs. The meaning of the message may not always be clear to you, but it should be clear to the system developer where the message came from.

  • Reproducibility - Indicate if this problem is reproducible now, or if it has happened previously.

  • Context - Describe any relevant context to this problem. (eg. It only happens when I am resting my feet on the keyboard.)

  • Consult - Consult the available knowledge bases (person expert with the system, wiki pages, manuals, IssueTrak, etc.) to learn if there is a known solution or work around to this problem.

  • Analysis - Provide your own analysis if you think you understand the cause of the problem. Make it clear in the description that this is your analysis, otherwise stick to just the facts.

  • Double Check - Check the text of your problem report for accuracy before submitting. Simple typographical errors can cause lots of confusion especially when acronymns are involved.

  • Priority - Choose the priority of your problem wisely. "Critical" means we are dead in the water and the problem is directly stopping the planned observations. "High" means the problem may be reducing efficiency, or degrading image quality, but observations are able to continue. "Medium" means the problem is significant, but does not require immediate action. "Low" means that we ought to fix it someday in the future.

-- JohnHill - 14 Jul 2008
Topic revision: r1 - 14 Jul 2008, JohnHill
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback