Re: An Ada advocacy method

[Marin David Condic <nobody@noplace.com>]

Documentation can only be as good as the writer. Let's put this in 
perspective. Take your average program in your average editor and 
highlight some system provided subroutine and hit the "Help" key. If you 
got nothing, that's pretty typical and usually pretty useless. If you 
got a single sentence saying "This is the gazorenthorpe subroutine", you 
got something close to useless. If it gave you a page that described 
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.

Microsoft may not have written Shakespearian quality documentation, but 
in my book, something more than "nothing" is pretty nice to have. In all 
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.

MDC



Wes Groleau wrote:
> 
> Define thorough.  If it's like most Microsoft documentation,
> it means lots of words in lots of files, but it does not mean
> something one can actually get any assistance from.
> 
> Apple's online help is just as useful as Microsoft's.  But
> at least they don't try to hide the fact by making it LOOK
> like an encyclopedia.
> 
> (I am not trying to claim that Ada has anything better!)
> 


-- 
======================================================================
Marin David Condic
I work for: http://www.belcan.com/
My project is: http://www.jast.mil/

Send Replies To: m c o n d i c @ a c m . o r g

     "In general the art of government consists in taking as
     much money as possible from one class of citizens to give
     to the other."

         --  Voltaire
======================================================================