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