[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Rename docs to "HOWTO's" (was Re: in defence of man pages)



At 09:47 23/09/99 +0000, you wrote:
>one of the reasons I have shifted from linux to OpenBSD is the quality
>of the man pages (far better on OpenBSD).
>
>I don't see the point of "HOWTOs" you just need well written man pages
>with examples.  I would rather have one standard set of docs with the
>system.

the goals of HOWTO's and man pages are diferent. It's dificult to think
of a man page that would talk about 5 or more ways to connect to your isp,
for instance. A howto named "Connecting to your ISP" could do it.

If you look at the openbsd FAQ, it isnt just a FAQ anymore. It's more like
a manual, with HOWTO's integrated. Like chapter 11 would be "How do I
get better performance?", and so on. Many itens could be cut to form a
HOWTO.

The job of writing is the same for howto's, man pages or FAQ's, i just
think people in misc@ should decide if it's better to rename some
documents to "HOWTO's".

Someone on misc@ (sorry, i dont remember who) said that he was scared
by man pages on linux, so he always went to linux.org to look for
HOWTO's. A lot of people are used to linux man pages, which are useless
and bad written. Then when they install openbsd and have a doubt, they
don't even try to look at "those damn useless man pages". They go
to the web and don't find anything named /how to/.

What I really think is that openbsd have a lot of "HOWTO's" that
aren't called this way, like "info kth-krb" and some man pages.
It's just a question of how it is called, and personally i think
HOWTO's are a good way to organize documents (better then a FAQ) and
it is something easier to write. If someone has just setup something
that wasn't trivial and he thinks other might be interested in how
he did it, he could just write a quick HOWTO, and update it himself.

Regards,

- Gustavo Henrique Maultasch de Oliveira
<gustavoh@sysadmin.com.br>