Re: what i've learned, and explanation.

[Rob Mahurin <robm@mad.scientist.com>]

On Fri, Apr 13, 2001 at 09:05:43AM +0100, Glyn Millington wrote:
> Seems to me that there is a problem for real newcomers with the docs -
> for the very reasons that make them so useful to those who know their way
> around a little. So much variety, so little time.
> 
> What might help is a daily post to the list with a subject line
> "NEW TO LIST? READ THIS!!"
> 
> containing some basic advice on how to ask for help and on one or two
> basic resources (like "man foo" and "apropos foo").  Not knowing how to
> ask seems a recurring problem that often sparks the kind of debate we've
> just seen.
> 
> I'd gladly do this if it seemed good to ....  whom ?  But with only a
> dial up connection and occasional holidays the output might be somewhat
> sporadic.
> 
> Worth pursuing?

I think this is a wonderful idea and I'd love to help out.  I would
suggest that instead of a daily post, this FAQ should be included in
the confirmation that you get when you subscribe to the list, or
perhaps sent as a second message at the same time; I've copied this
post to listmaster@lists.debian.org to ask if this is feasible.

I imagine the following format:

--- begin hypothetical message ---
Subject:  Frequently Asked Questions on debian-user

You have subscribed to debian-user, the general discussion forum for
the Debian GNU/Linux community.  This list is read by thousands of
Debian users and developers and typically generates about a hundred
messages a day.  It is also mirrored as the newsgroup [blah] and
archives are available at [blah].  

There is no "official technical support" for Debian as there is for
commercial software; this list is about as close as anything gets.
The people who read this list are mostly ordinary users who like to
help people figure out problems.  This means that if you ask a vague
question (e.g., "Why doesn't sound work?  Please hurry, it's urgent!")
you probably won't get much help --- although you will more than
likely get a request for a more detailed message.  

This document is designed to help you ask good questions.  Your
question has a greatly increased chance of getting a useful answer if
it:

o  indicates that you have read the relevant documentation, or at
	least tried to (section 1);
o  is precise about the problem, including model numbers of relevant
	hardware, the exact output of error messages, software version
	numbers, etc. (section 2);
o  [follows some other advice ...]
o  is polite :) 

To that end, the rest of this document has the following structure:

1.  How to Find (and Understand) Documentation
	1.1  Figuring Out the Name of a Command 
		apropos
		[tab][tab]
		... ?		
	1.2  Figuring Out How to Use a Command  
		man
		info
		/usr/doc/
		READMEs
		... ?
	1.3  Installation Documentation [should perhaps be first?]
		URLs
		files on the CD-ROM
		... ?
	1.4  More General Documentation
		LDP & /usr/doc/HOWTO/
	1.5  ...?

2.  How to Ask A Good Specific Question
	2.1  Copy the Exact Text of Error Messages!!!
	2.2  Identifying Software
		foo --version, man foo, dpkg {-S,-L,--status} foo, ... ?
	2.3  Identifying Hardware
		find the manual, contact the manufacturer (phone or
		web), open the case & look at the numbers, ... ?
	2.4  ... ?

--- end of hypothetical message ---

Please comment.

Rob

-- 
Q:	Know what the difference between your latest project
	and putting wings on an elephant is?
A:	Who knows?  The elephant *might* fly, heh, heh...