Documentation (Was: Re: [1.2 installation]: how to tell X to ...)

["Daniel S. Barclay" <daniel@compass-da.com>]

> From: Rick Macdonald <rickm@vsl.com>

> ...  the manual pages have fallen out of context... and there is
> > no index table to get a quick look at where to begin.
> 
> Not so!
> 
> Consider installing tkman, rman and glimpse, all in non-free.
> This requires tcl/tk, too.
> 
> Of course, this is only available _after_ you have X working,
> so it doesn't help with the initial installation, but you should be
> aware of this great tool for future use.
> 
> With one click, you can very quickly search every man page (or a subset
> of the manpath) for any string in the body of the man pages.

Those sound good.

However, how are users supposed to find out about those things?
(Not to say your suggestion is bad, but to address how to make that
information easier to find.)

Several comments / suggestions / questions / other ramblings, some directly
on this, and some on documentation more generally:

1.  I wish more old things pointed to new things (new things that replace or
	just enhance them), especially in manual pages (or wherever we think
	users usually look for definitive documentation).

	(You can find out you're doing things the wrong way or an old way
	by mentioning it on a mailing list, but that knowledge (from people
	who know about newer things) doesn't get captured in the written 
	documentation as much as it might.)

	I know a new package can't modify an existing manual page 
	(especially when you haven't even loaded the package on your system 
	yet), but...

2.  ...maybe creators and maintainers of new packages could ask maintainers 
	(at least of documentation) of older packages to add links to the 
	manual pages (etc.)


3.  Keep in mind that it's hard to keep up with constantly-changing
	documentation.  That is, a new user probably would read all
	the HOWTOs, README files, etc., to get started, but after that,
	it's impossible to re-read everything just to find the changes.
	
	I would think that direct-lookup on-line documentation like manual 
	pages or GNU info pages would be used on a continuing basis, so
	I would hope that all new information would make it into that
	reference documentation, and hopefully a few pointers to new,
	alternative, or add-on things could be included too.


Oh...whatever.

Daniel






	



--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-user-REQUEST@lists.debian.org . Trouble? e-mail to Bruce@Pixar.com