Page tree

Anybody who has written software for public use has probably received at least one bad bug report. Reports that say nothing ("It doesn't work!"), reports that make no sense, reports that don't give enough information, reports that give wrong information cannot help improve a software.

Ideally everybody who reports bugs for 4PSA products should read this article before reporting any bugs.

In bug reports, try to make very clear what are actual facts ("I was at the computer and this happened") and what are speculations ("I think the problem might be this"). Leave out speculations if you want to, but don't leave out facts.

When you report a bug, you are doing so because you want the bug fixed. There is no point in swearing at the programmer or being deliberately unhelpful: it may be their fault and your problem, and you might be wright to be angry at them, but the bug will get fixed faster if you help them by supplying all the information they need.

"It doesn't work."

Give the programmer some credit for basic intelligence: if the software really didn't work at all, they would have probably noticed. Since they haven't noticed, it must be working for them. Therefore, either you are doing something differently from them, or your environment is different from theirs. They need information, so providing this information is the purpose of a bug report. More information is almost always better than less. Include here everything you think it might be useful.

If you are not reporting a bug, but just asking for help using the program, you should use the product documentation, knowledge base, or the 4PSA Help Desk. If you want to suggest some feature request, please post on the 4PSA community.

Exact Replication Steps

If you want a bug to be well understood and fixed, we have to be able to replicate it. You want the programmer to run their own copy of the program, do the same things to it, and make it fail in the same way. When they can see the problem happening in front of their eyes, then they can deal with it. Do not report bugs like "Sometimes when I click ... some unknown message appears", these bugs probably won't be fixed.

So tell them exactly what you did. If it's a graphical program, tell them which buttons you pressed and what order you pressed them in. If it's a program you run by typing a command, show them precisely what command you typed. Give the programmer all the input you can think of.

Always Use the Latest Version of the Software

Always report bugs on the latest version of the software. There are good chances that the bug you report to be fixed in the latest version. Therefore, before filling a bug report, update the software to the latest release. Be aware that the build number is very important when you report bugs. This will help us track the issue in a specific release.

Clear, Correct and on Target

Writing clearly is essential in a bug report. If the programmer 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 what you did. Almost always 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. Due to this communication it might take weeks for the programmer to understand the issue.
  • 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 which should produce the failure, try following them yourself, to see if you missed a step.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.