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
-
AlmaLinux OS Kitten 10 Gives Power Users a Sneak Preview
If you're looking to kick the tires of AlmaLinux's upstream version, the developers have a purrfect solution.
-
Gnome 47.1 Released with a Few Fixes
The latest release of the Gnome desktop is all about fixing a few nagging issues and not about bringing new features into the mix.
-
System76 Unveils an Ampere-Powered Thelio Desktop
If you're looking for a new desktop system for developing autonomous driving and software-defined vehicle solutions. System76 has you covered.
-
VirtualBox 7.1.4 Includes Initial Support for Linux kernel 6.12
The latest version of VirtualBox has arrived and it not only adds initial support for kernel 6.12 but another feature that will make using the virtual machine tool much easier.
-
New Slimbook EVO with Raw AMD Ryzen Power
If you're looking for serious power in a 14" ultrabook that is powered by Linux, Slimbook has just the thing for you.
-
The Gnome Foundation Struggling to Stay Afloat
The foundation behind the Gnome desktop environment is having to go through some serious belt-tightening due to continued financial problems.
-
Thousands of Linux Servers Infected with Stealth Malware Since 2021
Perfctl is capable of remaining undetected, which makes it dangerous and hard to mitigate.
-
Halcyon Creates Anti-Ransomware Protection for Linux
As more Linux systems are targeted by ransomware, Halcyon is stepping up its protection.
-
Valve and Arch Linux Announce Collaboration
Valve and Arch have come together for two projects that will have a serious impact on the Linux distribution.
-
Hacker Successfully Runs Linux on a CPU from the Early ‘70s
From the office of "Look what I can do," Dmitry Grinberg was able to get Linux running on a processor that was created in 1971.