Re: Online help (was: An Ada advocacy method)

[Wes Groleau <groleau@freeshell.org>]

Marin David Condic wrote:
> Documentation can only be as good as the writer. Let's put this in 

And the writers of most (not all) online help files
should have been politications--they don't let their
lack of anything to say stop them from generating
plenty of words.

> got a single sentence saying "This is the gazorenthorpe subroutine", you 
> got something close to useless. If it gave you a page that described 

If the thing I pointed to was the identifier "gazorenthorpe,"
it would be _completely_ useless--yet typical of much of the
help files from Microsoft, Apple, Dell, Gateway, Rational,
Sun, and numerous other vendors.

> what the subroutine is supposed to do and what the parameters are 
> supposed to be and maybe an example or two of proper usage and perhaps 
> some links to similar or related subroutines, you got something that is 
> a damned sight better than "nothing" or a single sentence.

Indeed it would be.  I'll have to take your word for it if you
say that M$ broke character and did that sort of thing for MSVC++

> my usage of MSVC++ and my many trips into the documentation, I usually 
> could find out what the average programmer needed to know in order to 
> use some provided feature and that's a reasonable definition of 
> "thorough" so far as I can tell.


-- 
Wes Groleau
   ----
   The man who reads nothing at all is better educated
   than the man who reads nothing but newspapers.
                             -- Thomas Jefferson

   The man who reads nothing at all is at least as educated
   as the man who reads nothing but online help.
                             -- Wes Groleau    :-)