Writing clearly is essential in a bug report. If the technical support person can't tell what you meant, you might as well not have said anything.
· Be specific. If you can do the same thing two different ways, state which one you used. "I selected Load" might mean "I clicked on Load" or "I pressed Alt-L". Say which you did. Sometimes it matters.
· Be verbose. Give more information rather than less. If you say too much, the programmer can ignore some of it. If you say too little, they have to come back and ask more questions. One bug report received was a single sentence; every time the customer had to be asked for more information, the reporter would reply with another single sentence. It took several weeks to get a useful amount of information, because it turned up one short sentence at a time.
· Be careful of pronouns. Don't use words like "it", or references like "the window", when it's unclear what they mean. Consider this: "I started FooApp. It put up a warning window. I tried to close it and it crashed." It isn't clear what the user tried to close. Did they try to close the warning window, or the whole of FooApp? It makes a difference. Instead, you could say "I started FooApp, which put up a warning window. I tried to close the warning window, and FooApp crashed." This is longer and more repetitive, but also clearer and less easy to misunderstand.
· Read what you wrote. Read the report back to yourself, and see if you think it's clear. If you have listed a sequence of actions that should produce the failure, try following them yourself, to see if you missed a step.
Summary
· The first aim of a bug report is to let the support person see the failure with their own eyes. If you can't be with them to make it fail in front of them, give them detailed instructions so that they can make it fail for themselves.
· In case the first aim doesn't succeed, and the programmer can't see it failing themselves, the second aim of a bug report is to describe what went wrong. Describe everything in detail. State what you saw, and also state what you expected to see. Write down the error messages, especially if they have numbers in those messages.
· When your computer does something unexpected, freeze. Do nothing until you're calm, and don't do anything that you think might be dangerous.
· By all means try to diagnose the fault yourself if you think you can, but if you do, you should still report the symptoms as well.
· Be ready to provide extra information if the programmer needs it. If they didn't need it, they wouldn't be asking for it. They aren't being deliberately awkward. Have version numbers at your fingertips, because they will probably be needed.
· Write clearly. Say what you mean, and make sure it can't be misinterpreted.
· Above all, be precise. Programmers like precision.