[Re: GLLUG meeting topics]

[Matt Graham]

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.

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.

[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.

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.)

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.)

Argh.  I guess in the end, if documentation writers don't think the way the
end-users are going to think, then the users will be confused, sometimes
permanently.
[/random_thoughts]

> Ah, yes.  But nothing is so handy as `man -k`  I am of the opinion that 
> subsequent online documentation features across most platforms (ie. 
> Solaris Documentation Server) have failed, at least insofaras people still 
> overwhelmingly rely on `man` for online help.  Especially since virtually 
> anyone can write a man page and install it to a system, either as part of 
> a package or on its own.  It's just one of those things.  Heck, even 
> non-root users can transparently augment the man pages available to them 
> simply by adding any path to their $MANPATH shell variable.  Personally, I 
> don't think I could live without them.  I sure would own a lot more dusty 
> books, that's for sure.

AOL.  It irritates me that GNOME/KDE programs don't seem to have man pages. 
There's always --help, and the "Help" menu item leads to HTML help, but
still...

-- 
Matt G / Dances With Crows
There is no Darkness in Eternity
But only Light too dim for us to see

____________________________________________________________________
Get free email and a permanent address at http://www.netaddress.com/?N=1