[Re: GLLUG meeting topics]

[Ben Pfaff]

Matt Graham <danceswithcrows@usa.net> writes:

> Paul_Melson@keykertusa.com wrote:
> > >It takes awhile to get used to man pages.  I prefer the help menus of 
> > OpenVMS, myself.
> 
> Never seen those, but what about "info"?  The main problem with
> a hierarchical help system like info is that the information
> you're looking for is not always organized in a helpful manner.
> See the info page for tar, for example... many subnodes, many
> of which duplicate information, some of which are a bit
> misleading.

[BTW, your lines are too long.  I've reformatted the quoted text
so that it fits nicely on an 80-column screen.  RFC 1855
recommends max 65-column paragraphs so as to allow a few levels
of quoting on an 80-column screen, so that's what I use.]

The tar documentation sucks.  This is because it has never been
properly completed.  There were omissions, duplications, and
simply incorrect statements, the last time I checked.  (I'm sure
they'd be willing to take contributions of improved documentation
if you're interested...)

Don't confuse problems with one Info document with problems in
the system.  Info has at least one big advantage, IMO: a
searchable index.  This saves me a *lot* of time sometimes.

> For reasonably short things (<1000 lines?) I think having a
> flat manpage combined with a search-capable pager would work
> better than trying to organize a hierarchy.  Complex things
> like bash and perl work better in some sort of hierarchy.

You know that Info has full-text search, too.  Just hit `s'.

> [random_thoughts] 
> Actually, I've been thinking about this in the back of my head for a while. 
> The user interface gurus say that "normal humans" don't *get* hierarchies and
> don't understand the notion that directories have subdirectories which can
> contain files....  However, documentation is becoming more and more
> hierarchical (see any recent MSDN collection) and the imposition of a
> hierarchy on information can skew the usefulness of that information.
> 
> Example, taken from a few-months-back experience with MSDN:  _open returned
> 80.  What does that mean?  Look up _open, it lists a number of symbolic error
> values, none of which evaluates to 80.  Look up "80", find nothing useful,
> look up variations on "numeric error codes", find many useless pieces of info,
> finally find a complete list of the error codes a syscall can return under
> "System Errors - Numerical Order : NT 3.51 Reference".  All well and good,
> except for that it took 10 minutes and could've taken much longer if I'd been
> looking for something really obscure.

This is a big problem with MS documentation, in my experience.  I
once spent a whole afternoon searching through MSDN
documentation[1] looking for some sort of function to help with
sending an email message.  I'm sure it was buried in there
somewhere.  I eventually gave up and found a third-party package.

[1] I got hired for a rather nasty little project by a company
whose owner I owe a favor or two.

> I don't know how this could've been handled more efficiently--there's a lot of
> info there, and many search tools, and a reasonable organization of topics and
> subtopics.  However, there's no last-resort search method that would be
> comparable to starting at page 1 of a book and reading straight through to the
> end while looking for a user-supplied keyword.  (Bonehead Search, the least
> efficient way of doing these things, but sometimes too clever = dumb.)

There isn't?  ISTR that the MS Help facilities include a
full-text search.

> In large agglomerations of manuals, people also tend to get lost in a maze of
> electronic documents that all look alike (same color scheme, same typefaces,
> etc.)  Paper manuals tend to provide more clues that aid recognition ("I think
> bogo-sort was described about 3/4 of the way through the book with the moray
> eel on it") and electronic documents could do the same (pages describing Foo
> have an image of a zebra at top and red headings, pages describing Bar have an
> image of a wombat at top and puce headings, etc.)

Hmm.  That *is* interesting.  But how would you tell the computer
to search for a picture of a wombat?

-- 
Only wimps use tape backup: _real_ men just upload their important stuff
on ftp, and let the rest of the world mirror it ;)
        -- Linus Torvalds