Many a frustrated user has uttered the words "It is not working!" This anguished phrase, whether on the phone, in email or in an online forum, strikes terror into the heart of a front-line telephone support person. For the phrase has told them nothing other than "something" has failed or is failing.

Training users in how to make a useful problem report helps both the user, by helping them get their problem fixed in the shortest possible time, and the developer, by getting them useful information.

Gather Information

In generating a problem report, gather as much information about the problem as you can in the hope that you might get an answer on the first contact.

Who is the manufacturer and what is the model number of the system? What is the architecture? For example, is it Intel, AMD, or Sun Sparc? And what type of processor and speed is it? This type of information typically does not change through the life of your machine, so when you buy it, copy down this information and put it in a safe place where you can find it.

Also, make sure you have written down how much main memory you have, the number and type of hard disks, and what types of peripherals you have, including the make and model of the video card and sound board.

Some distributions of Linux have "hardware detection" programs built into their systems administration menus that will help you determine what hardware you have. Now that your hardware is more or less specified, you can go on to the software. What Linux distribution do you have, and what is the release number? Have you applied all the patches that have been issued by your distribution?

Next, you have to determine what part of the system is creating the problems. The menu item that you used to launch a particular application typically does not show the real name of the application. Try looking at the window manager bar (if you have one) at the top of the window to see whether the name of the program is there – for example, "gedit." Failing that, look at some entries in the help menu for the application (assuming one exists) and see whether one of the entries tells you more. In my gedit example, I find that it is gedit 2.24.2.

Try to limit the problem scope as much as possible. Is one particular file creating the problem? After making a copy of that file (for safekeeping), perhaps you can make it smaller while still maintaining the same failing characteristics so you can more easily show someone the issue that you are trying to fix. When you have the input file as small as you can get it and still demonstrate the problem, file it away as your "demonstration file."

Write down the steps that it takes to illustrate the problem from the first time that you invoke the program to the time the problem actually occurs with your demonstration file.

Try to eliminate all of the usual "bad user on device" reasons for why things fail. Stories abound about having to battle help desk personnel who ask whether your mouse is plugged in or whether you have enough disk space, but they ask these questions for a reason. You do not want to be caught in the position of having to say, "Oh, never mind!"

Help Online

Before you try to report your problem, to save everyone a bit of time, try to locate a previous example of it. At this point, you can probably formulate a good search query to see whether someone else has reported the same problem.

As an example, say that gedit does not do a Find and Replace when you specify that in a search. Gedit finds the string, but does not replace it. To see whether anyone else has reported your problem and, if so, whether they have a fix, you can search the Internet for the strings "gedit" and "replace."

Try to find the project's website and see whether they have a forum that you can seach for a previously reported example of your problem. A workaround or fix for the problem might have been found that just has not had time to work itself into the code base and back to you. Although this might be a website for your particular program, you should also check the distribution's website.

If you have not found the answer to your problem, it might be time to call the help line, send email, or put your problem description into a forum, but at least you will be ready for most of the questions that come your way to help determine the cause of your trouble.