Launchpad Entry: https://launchpad.net/ubuntu-doc/+spec/troubleshooting-guide
Created: June 07, 2008 by NickEllery
Contributors: NickEllery
Packages affected: https://launchpad.net/ubuntu-doc
Summary
A troubleshooting section for each category of the documentation intended for new users will provide quick solutions on common questions. This will help to lower the amount of simple questions on the forums and other support sources. The goal is to have this completed at the end of the IntrepidIbex release cycle.
Rationale
Every single new user to Ubuntu will encounter a problem, in some way or another. Troubleshooting docs containing the most common issues would greatly assist new users.
Use cases
Steven heard about an operating system called Ubuntu, and decided to give it a try. Upon installing Ubuntu, he decided to install some applications via Synaptic. After installing several programs, he closed Synaptic. He then remembered there was another application he wanted to install, so he re-opened Synaptic. He then discovered that he could not run Synaptic because he had a dpkg --configure -a error. His first instinct was to look through the documentation to find information on the topic, but could not. He then went to the forums, where he asked about this issue, and had a reply and solution within 5 minutes.
- Elvis just installed Ubuntu, but is unable to access any web pages when he starts Firefox. He can't retrieve his email either. Elvis isn't very good with computers, and doesn't know what could be wrong and how he might go about trying to fix the problem.
- Buddy is a bit of a music buff, and has decided to try Ubuntu to see if he likes it. On inserting a music CD into the CD drive, the CD seems to be playing but he can't hear any sound. He plugs his MP3 player into the computer and can't hear any of the MP3 files when he plays them either. His speakers seem to be turned on, and he can still hear sounds on Windows, so he hasn't got a clue what could be wrong.
- Chuck installed Ubuntu, but found that all of the icons and text look big and stretched. He can barely fit a whole paragraph of text onto the screen - it's like looking at a computer screen from 1993! Chuck thinks that something is probably wrong, but doesn't really understand how to change the size of things on the screen.
Design
The troubleshooting guide could be divided into sections, for different issues. Each of these categories will be synced and placed in each of the Official Documentation pages.
Those will be:
- Adding and Removing Software
- Files, Folders, and Documents
- Desktop Customization/Graphical Problems
- Internet/Connectivity
- Music, Video, and Photos
- Printing and Faxing
Implementation
A list of some common questions that have been asked in the forums can be found here.
Outstanding issues
There are an extremely large amount of issues that a user that could encounter. It is best to keep the guide at a readable length, so choosing the most common issues will be a necessity.
Comments
We need to be careful about designing these guides properly before we start writing them. Without a decent structure, they could end up being an unnavigable mess. -- PhilBull
- I'm not convinced on the need for this. Troubleshooting guides are great for situations where the user is unable to go straight to Google for the answer (such as connectivity issues). In the sited example, I can see most users typing that dpkg message into Google. That may well send them to the forums, it may not. I am also not convinced that we take the forums as the font of all knowledge because in many situations there is some well intentioned but extremely misguided information and there is no method of reporting such information as bugs, as there is in the system documentation. -- ddrichardson
- Some of what is being proposed here is not troubleshooting, it is FAQ. Faws are OK for forums with huge numbers of people who don't search the forum before posting a common questions and in situations where there are limited options. Defining what should and should not be in an FAQ is a massive task that, frankly, I see little value in, especially when people are more likely to follow a topic or search based approach to finding the information they need. -- ddrichardson
- If troubleshooting is worth pursuing, then we should focus on one area, specify, develop, test (and openly test amongst the target user group) and then implement further. -- ddrichardson