How to report problems effectively
From BigSoft
Contents |
[edit] Introduction
Effective issue reports are more likely to be corrected. These guidelines explain how to write such reports.
[edit] How to report
- Be precise
- Be clear - explain it so others can reproduce the bug
- One bug per report
- No bug is too trivial to report - small bugs may hide big bugs
- Clearly separate fact from speculation
[edit] Be precise
Don't assume the person dealing with your request knows how your system works. Try to include all the steps you have made to create the problem. Please write the issue body in English. BigSoft deals with different industries, all of whom have their own set of acronyms and jargon. Acronym's are becoming more popular on the internet, but it is much better to read it in full. Storage is cheap these days so there is no need to use them. When talking about multiple accounts on multiple servers things can get a bit more difficult. While writing you may find that you are using words or phrases like "it", "them", "my account", "the other machine", if this happens then we may have to ask you to clarify what you mean, which is an additional step you wouldn't have needed to make.
[edit] Be clear
The objective is to allow us to reproduce the problem. Once we have done that, a solution is not far behind.
[edit] One bug per report
It is very easy to get carried away and start listing all the problems in the same place, but try to separate them out. Don't worry if they are similar. If it turns out they are actually the same problem then we can flag the duplication on the system. If it turns out that all your problems are related to each other, then our system can describe that relationship. You may not be aware of it, which is why we need you to report them individually.
[edit] No bug is too trivial to report - small bugs may hide big bugs
The granularity of bug reporting can help with a speedier solution.
[edit] Clearly separate fact from speculation
It is nice to get help on a solution, so if you think you know what the problem is, or what the problem is related to then add it as a footnote. Try to keep the issue's body clearly separated, so that it does not confuse the problem at hand.
[edit] Summary
In a nutshell, the aim of a bug report is to enable the support engineer to see the program failing in front of them. You can either show them in person, or give them careful and detailed instructions on how to make it fail. If they can make it fail, they will try to gather extra information until they know the cause. If they can't make it fail, they will have to ask you to gather that information for them.
[edit] Examples
[edit] Mail issues
"I can't get my mail from my computer"
- What is the mail account?
- Where are you when you access you mail?
- What is the operating system you are running on your computer?
- What is your mail client?
- What is your mail client version?
- How are you accessing POP/IMAP?
- What does it say to let you know it isn't going to do what you want?
[edit] Authentication issues
"It wouldn't let me login"
- What wouldn't?
- What are you trying to log in as?
- Where are you logging in from?
- What does it say when it fails.
[edit] Hardware
"The printer has stopped work"
- Which printer?
- How do you identify it?
- What model is it?
- How are you printing to it?
[edit] General
In all cases it does something. Even if it does nothing - that is something. If it returns nothing - that is a clue. If it waits for ages then does nothing - that is 2 clues. Get the idea?
