On Thu, 6 Jul 2000, Derek Martin wrote:
> Which is great, except for the oft overlooked idea that TEXINFO SUCKS.
IMO, it isn't so much texinfo (which is just an encoding format, after all)
but the "info" viewer/browser program that really sucks.
> Either that or the author of every texinfo manual I've ever read or
> attempted to read (more than a few) just don't have the knack of it.
There is something a lot of documentation writers fail to realize, and that
is that there is more then one kind of documentation.
There are reference manuals, which tell you how to use a tool, but generally
don't focus on "the big picture" as much. Your typical Unix manpage falls
into this category.
There are functional guides, which take you though all the features of a
program, in structured order, focusing on the "why" as much as the "how".
GNU texinfo manuals tend to be this sort of documentation, if anything.
There are step-by-step instructions, which focus primarily on getting the
package working in a typical configuration. The LDP "HOWTOs" are excellent
examples of this.
Ideally, you get all three. In reality, we're often lucky to get one.
But, it has been said: Documentation is like sex. When it is good, it is
very, very good. And when it is bad, it is still considerably better then
none at all.
> Man pages are much clearer ...
LOL. I've read some pretty bad manpages in my time. And I ain't that
old. :-)
--
Ben Scott <[EMAIL PROTECTED]>
| "He who fights monsters should see to it that in the process he himself |
| does not become a monster." -- Frederick Wilhelm Nietzsche |
**********************************************************
To unsubscribe from this list, send mail to
[EMAIL PROTECTED] with the following text in the
*body* (*not* the subject line) of the letter:
unsubscribe gnhlug
**********************************************************
