On Wed, Apr 21, 2004 at 07:08:45PM +0200, Jan Nieuwenhuizen wrote:
> Wouter Verhelst writes:
> > I never said that; I only said that good on-line documentation should
> > concise and to-the-point information. Full, extensive documentation
> > should be put in a HOWTO, a book, or on a website -- not in the primary
> > on-line documentation tool.
>
> Why do you want (at least) two documentation tools?
Are you suggesting that "foo --help" should contain everything,
including underlying concepts and references to other documentation? If
not, then you, yourself, are also suggesting more than one source of
documentation.
My point is: there are different types of documentation sources for
different purposes. --help output should not try to be complete;
similarly, on-line documentation does not have to contain information on
underlying concepts if they are rather complex.
> I really dislike having to travel down the path of possible sources of
> documentation.
I much prefer different sources of documentation with different
purposes: --help output for answering quick "how was it again" type of
questions; on-line documentation (such as manpages, or on-line help)
documenting options and features; and books, HOWTOs, manpages from
section 7 (although those aren't used that often on (GNU/)Linux), or
other similar things documenting the "bigger picture".
If those purposes get messed up, then having to travel down the path of
possible sources is, indeed, painful; if that's not the case (and I
often find it isn't), there is no problem, and it in fact helps you
(because you don't get information you're not looking for).
> In general, I like info pages a lot, I can live with man pages,
Well, we disagree here, but that isn't new, right?
> find .txt.gz files in /usr/share/doc/* a bit clumsy.
It depends.
> But sometimes it gets worse, and there aro only .html pages or .ps.gz.
> That's really annoying because there is no good search function or
> index.
Can't agree more here.
> > This requirement allows a user to log on to a system, type "man foo",
> > and get documentation; such consistency is good.
>
> Yes, consistency is good. However, I'm quite happy with the the
> python info pages, but think that `man perl' is broken beyond repair;
I don't really like "man perl" either.
> it illustrates why `man 2 open' is fine, but `must have man' does not
> guarantee sanity or bring enlightenment.
Hm. I never intended to say that; if I have, apologies.
What I meant to say is that, IME, info pages tend to lean towards
over-documentation, so that one does not easily find the documentation
one needs anymore. Since manual pages need to be put everything on one
page, you don't see the same thing there.
I'm not suggesting that all manpages are great, or that all info pages
are crap. What i'm suggesting is that due to the difference in format,
manpages usually contain documentation better suited for on-line
documentation than info pages do.
> > Since there's much more software that has manpages but no texinfo
> > documentation than the other way around, it's far easier to require
> > manpages than it is to require texinfo.
>
> Yes, that's easier for the developer, but it's a lot less useful for
> the user. I prefer better usability, if possible.
Requiring developers to write extensive info pages on software they want
to package before they get it uploaded will probably result in less
inclination to package software (and, thus, to document them). I assert
that is less useful than having "more useful" documentation, even if I
would agree that info generally is indeed more useful than manpages
(which I don't).
> > If you have more information, I'm happy to learn about it; let me
> > start off by disagreeing with the stance that being "terse" or
> > giving "inadequate explanation of the underlying concepts" is
> > necessarily a problem.
>
> There's also
>
> In general, a GNU manual should serve both as tutorial and
> reference. It should be set up for convenient access to each
> topic through Info, and for reading straight through (appendixes
> aside). A GNU manual should give a good introduction to a
> beginner reading through from the start, and should also provide
> all the details that hackers want. The Bison manual is a good
> example of this--please take a look at it to see what we mean.
Yeah, well, that's braindead.
For a good tutorial, one needs an easy to read text that does not
necessarily document everything, but one that leads the user through the
major concepts of the program, and points out a few interesting features
here and there without going in too much detail. In the name of
simplifying things for the reader, it's no big deal if a tutorial isn't
fully accurate at the beginning, so long as confusion is cleared out
later. It's not necessary to be able to pick just part of the tutorial;
to really make a tutorial useful, one should be able to read it start to
end; and after doing that, one should at least have an understanding of
how the software works.
For a good reference, an easy to read text is not required; rather, good
reference documentation contains every detail on every part of the
software, no matter how unimportant in the bigger picture, and it should
do so without errors or without simplification. It's not necessary for a
good reference manual to have an easy readable text which can be read
start to end; rather, a reference manual should consist of small blocks
of detailed information which can each be read separately, and which
point to related items.
These two types of documentation are so fundamentally different that
it's plainly impossible to make one text which can serve both purposes
well. Documentation which does serve as both a reference manual is
usually split up in a "Part I: Tutorial" and a "Part II: Reference" or
so. This is even the case in the above mentioned bison info pages; the
first page one gets after entering "info bison" clearly contains a
header "Tutorial section" and a header "Reference section". In fact, I
have yet to see the first piece of documentation that does not work like
that, that can be used both as a reference and as a tutorial, and that
is doing both jobs equally well (as opposed to equally bad).
If it's not possible to create one text that can be used for both
purposes; if it is indeed necessary to logically split up your text
anyway so that you effectively have two manuals in one, then why require
them to be part of the same document in the first place? That has quite
a few drawbacks too:
* People that need a tutorial don't always need the reference
documentation (yet), and vice versa; throwing them together and
forcing people to install both of them or none of them isn't really
nice.
* It makes looking for the required information harder. If I'm looking
at a manpage, using less as a pager, and want to find information on
the "--foo" option, I can hit "/--foo" and be fairly sure I end up
with the reference documentation of the "--foo" option. If I do the
same in `info', it is not at all certain whether I will end up with
either the reference documentation or a section of the tutorial that
happens to handle the --foo option (of course, redoing the same search
helps, but the point is that it's necessary to do that in the first
place)
* People that write good reference documentation are not necessary the
same people that write good tutorials. Forcing both types of
documentation to be part of the same source will either end you up
with one person doing all of it, thereby having a good tutorial and a
bad reference (or vice versa), one group working on the tutorial part
with another working on the reference part, resulting in better
documentation but unnecessary coordination; or one group of people
working on "everything" with overall bad documentation as a result.
> Just for fun, have a look at the bison info pages, and compare that
> with the FreeBSD yacc man page, for example.
[...]
> And that's all documentation there is. Your assignment: write a
> simple parser using yacc.
The FreeBSD manual page on yacc isn't meant as a tutorial on writing
LALR parsers, nor is it meant as a reference on the options one can have
while writing a parser. It is meant as on-line documentation for using
the 'yacc' binary from the command line, and does this job well.
> > As I said, IMO on-line documentation should contain concise and to
> > the point information; underlying concepts, if they're complex, and
> > other blatter, are for HOWTO's and books (either digitally or
> > printed).
>
> HOWTOs are often a desperate effort by users to make up for programs
> that lack good documentation.
True; but since they're usually written by people who do nothing but
play with the software, use it, write down their experiences, and
publish that, there are quite some HOWTOs that are pure beaty. Yes,
there are exceptions.
--
EARTH
smog | bricks
AIR -- mud -- FIRE
soda water | tequila
WATER
-- with thanks to fortune
Attachment:
signature.asc
Description: Digital signature