On Mon, 17 Jul 2000, Mike Cheponis wrote:

>Has anybody here actually looked at Microsoft's documentation?  Frankly,
>it is head and shoulders above what we have. 

Do you really think so?  In my experience it looks very pretty, but has
bugger-all useful content, and what there is, is so fragmented that it is
almost impossible to read all about a topic without following several dozen
hyperlinks.

For a more extreme example of what is wrong with hypertext, try using the
online documentation [sic] which comes with Borland C++ Builder.  Here, the
writers seem to be trying to handle the problem of dumbed-down morons with
limited attention spans by having no page which is much larger than about
3 paragraphs.  But it's a bit difficult to document a C++ class in 3
paragraphs, and as a result you once again have to find your way through
a twisty maze of hyperlinks, all very similar.  As someone in the Computer
Science department here once commented rather memorably "The trouble with
hypertext is that it's a lot of hype about not very much text".

Something like the C++ Builder documentation is probably just about usable
by someone who already knows what all the components do, and just needs
to check details occasionally.  But as someone who had never done any
Windoze (or C++) programming I found it fscking useless.  You want to see
ALL the description of a component, including all it's methods, all at the
same time?  Sorry, the hypertext system doesn't do that.  You want to see
ALL the description of two similar components, so you can decide which is
better suited to your requirements?  Forget it -- you can only see one
snippet at a time.  

Whenever I've started to work on a new system I've always browsed the
printed documentation to see what is available, and to get a rough idea
what each "thing" can do.  If you don't do this there's always a great
danger that you'll re-invent a wobbly version of a wheel which already
exists, or use a hammer to insert a screw (because you didn't realise
that you were supposed to use a screwdriver).  But try getting a printed
version of the C++ Builder crap.  I did this and got thousands of pages,
each documenting a single method or exception, printed in random order.
I sat on the floor in the middle of my office for two days trying to
sort this crap before giving up and throwing the whole lot in the bin.

I'm not saying hypertext can't ever work; just that I've seen a lot of
examples where it doesn't.  The good examples can be printed as a paper
document and read easily.  This means, for example, that hypertext links
should read "see Section A.B.C for more information about foo()", so
that the link makes sense in the printed copy.  But to get this sort of
detail right you have to discipline yourself to produce a printed copy
(and probably have someone else proof-read it).  I think the other main
failing is to break a single topic up into child-sized portions in the
mistaken belief that this will make it easier to read.

So I agree completely with Greywolf that man pages shouldn't go away.
I've nothing against adding extensions which allow the troff source to
contain hyperlinks so that it can be processed into HTML, but I don't
think there is anything wrong with the existing format of man pages.
Printed manuals are NOT obsolete, particularly when you need rapid access
to several different sections.

>Another cool thing about html-based documentation is that not only can it
>trivially use local files, but it can also access data over the net; this
>can be helpful for small systems that have a net connection but do not 
>want to waste local disk space for doc, or as a place where documentation
>updates are placed.

I've always found that an NFS mount of /usr/share/man (or whatever) works
quite well for this.


Roger

------------------------------------------------------------------------------
Roger Brooks (Systems Programmer),          |  Email: R.S.Brooks@liv.ac.uk
Computing Services Dept,                    |  Tel:   +44 151 794 4441
The University of Liverpool,                |  Fax:   +44 151 794 4442
PO Box 147, Liverpool L69 3BX, UK           | 
------------------------------------------------------------------------------