lists.debian.org: FAQ / tip-of-the-day

[will trillich <will@serensoft.com>]

On Fri, Apr 13, 2001 at 02:01:24PM -0400, Rob Mahurin wrote:
> On Fri, Apr 13, 2001 at 09:05:43AM +0100, Glyn Millington wrote:
> > 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 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.

daily is waaay too often. there's plenty of traffic on the list
already... YET a periodic re-post is not a bad (or original)
idea. many newsgroups publish their faq, sometimes multi-part
faq's, monthly or quarterly.

another thing for lists.debian.org and the team to consider might
be a random "TIP" in the email signature. the postgresql mailing
list bot does this, altho i've only seen five distinct tips (or
is it four) with debian we could have hundreds, easily!

something like

	Looking for apt-related commands? At your command prompt,
	type "apt" and then press TAB instead of ENTER.

or

	How do you set up your /etc/apt/sources.list file for
	apt-get?  Try apt-setup!

or

	Looking for commands dealing with web servers? Try the
	command "apropos http"!

similar to a fortune-of-the-day, but instead it's a
tip-of-the-email (three lines, max!) appended to the end of any
plain text message broadcast through the listbot server. hmm?

and we could munge together a way to have your average joe submit
his own (or jane, her own) tips to be included at random, surely.

--

and a list-related faq is still a good idea!

> I imagine the following format:
> 
> --- begin hypothetical message ---
> Subject:  Frequently Asked Questions on debian-user

nice start so far. add it to http://newbieDoc.sourceForge.net?

[snip]

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

that's /usr/share/doc/* these days

> 		READMEs

HOWTOs

> 		... ?
> 	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  ...?

redundancy in mentioning a document source is NOT a bad thing.
HOWTOs can be mentioned in fifteen different places on this FAQ
document, and it won't hurt a thing.

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

don't let anyone put a damper on this effort. it's important!
(and when you're done -- we prefer sgml, docbook style, but we'll
accept html -- add it to our itty-bitty library at newbiedoc over
at http://sourceforge.net/projects/newbiedoc/ !)

-- 
don't visit this page. it's bad for you. take my expert word for it.
http://www.salon.com/people/col/pagl/2001/03/21/spring/index1.html

will@serensoft.com
http://sourceforge.net/projects/newbiedoc -- we need your brain!
http://www.dontUthink.com/ -- your brain needs us!