Troubleshooting Guide

[Phil Bull]

Hi Dougie,

On Sun, 2008-06-15 at 13:18 +0100, Dougie Richardson wrote:
> I've posted some comments on this on the specification page:
> 
> * 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.

Yes, I think that that original use case wouldn't justify writing a
troubleshooting-type document. A more appropriate type of document for
that case would be a short "Fixing common problems with package
managers" section. Incidentally, does anyone fancy writing one of these?

I don't see this spec as being about producing a single document with
troubleshooting information on a range of problems. Rather, I think it
should be about planning a short series of troubleshooters for common
problems which don't have a single specific solution. We can then insert
these troubleshooters into appropriate places in the documentation. I've
updated the "Use cases" section of the spec [1] to reflect this.

> * 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

I think that we should define more clearly what we mean by
"troubleshooting". I see troubleshooting as a way of helping users with
a certain *type* of problem to diagnose the exact cause of the problem
so that they can solve it.

For example, the user might have the problem of "I can't hear any
sounds". There are a lot of different potential causes of this problem
(sound muted, volume set too low, no sound card drivers, hardware
unplugged etc.), so we ask the user to perform a few actions to find out
what the cause of the problem is. Once there is enough information to
identify the specific cause of the problem, we can then make
recommendations on how to fix it.

I think FAQs are very different to this - there's often a 1:1 mapping
between problem and solution, and the problem is normally reasonably
specific.

> * 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

I agree. We should specify what the broad problem is that we're trying
to solve (e.g. "I can't connect to the Internet"), research common
causes of this problem and then build the troubleshooting information
around them.

Thanks,

Phil

[1] - https://wiki.ubuntu.com/TroubleshootingGuide

-- 
Phil Bull
http://www.launchpad.net/people/philbull