Generating a good problem report
"It is not working!"
Help your support person help you: Gather information before you call.
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.
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
News
-
Latest Cinnamon Desktop Releases with a Bold New Look
Just in time for the holidays, the developer of the Cinnamon desktop has shipped a new release to help spice up your eggnog with new features and a new look.
-
Armbian 24.11 Released with Expanded Hardware Support
If you've been waiting for Armbian to support OrangePi 5 Max and Radxa ROCK 5B+, the wait is over.
-
SUSE Renames Several Products for Better Name Recognition
SUSE has been a very powerful player in the European market, but it knows it must branch out to gain serious traction. Will a name change do the trick?
-
ESET Discovers New Linux Malware
WolfsBane is an all-in-one malware that has hit the Linux operating system and includes a dropper, a launcher, and a backdoor.
-
New Linux Kernel Patch Allows Forcing a CPU Mitigation
Even when CPU mitigations can consume precious CPU cycles, it might not be a bad idea to allow users to enable them, even if your machine isn't vulnerable.
-
Red Hat Enterprise Linux 9.5 Released
Notify your friends, loved ones, and colleagues that the latest version of RHEL is available with plenty of enhancements.
-
Linux Sees Massive Performance Increase from a Single Line of Code
With one line of code, Intel was able to increase the performance of the Linux kernel by 4,000 percent.
-
Fedora KDE Approved as an Official Spin
If you prefer the Plasma desktop environment and the Fedora distribution, you're in luck because there's now an official spin that is listed on the same level as the Fedora Workstation edition.
-
New Steam Client Ups the Ante for Linux
The latest release from Steam has some pretty cool tricks up its sleeve.
-
Gnome OS Transitioning Toward a General-Purpose Distro
If you're looking for the perfectly vanilla take on the Gnome desktop, Gnome OS might be for you.