HOWTOs: reality check

[Marc Espie <Marc.Espie@liafa.jussieu.fr>]

On Thu, Sep 23, 1999 at 04:07:12PM -0500, alex wrote:
> Having said that, I have a much better understanding of where the man
> page people are coming from than I did yesterday.  I am one of those
> people who comes at this from a linux perspective, and the linux man
> pages are pretty bad.

The linux HOWTO pages are pretty bad as well.
Each time I had to dig thru pages of useless comments, jokes, copyright,
history, definition of fairly common terms, just to get  at the five lines
of info I needed.

when they were there.
Sometimes, the HOWTO grew so large that people stopped maintaining it.

> I still believe that HOWTOs can be useful, if only because they don't
> have to be comprehensive and can therefore be simpler.  Perhaps if I
> can write some good docs, some of you in the man page contingent will
> come around.

HOWTO can certainly be useful, as long as they have some qualities:
* conciseness (yep, less than manpages, but still)
* accurate
* up-to-date

Now, when it comes to writing and MAINTAINING such documents, the going gets
tough...

More often than not, someone writes a page, then just plain disappear, or
forgets about upgrading it.

You want more documentation ? 

You write it, AND YOU MAINTAIN IT.
I know that there's already enough documentation I have to keep up-to-date,
or that I wish were up to date without adding yet HOWTOs to that list.
-- 
	Marc Espie		
|anime, sf, juggling, unicycle, acrobatics, comics...
|AmigaOS, OpenBSD, C++, perl, Icon, PostScript...
| `real programmers don't die, they just get out of beta'