Re: An Ada advocacy method

[Dmitry A. Kazakov <mailbox@dmitry-kazakov.de>]

On Tue, 02 Sep 2003 01:10:15 GMT, Marin David Condic
<nobody@noplace.com> wrote:

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

It is true what you are saying. But two small corrections:

1. F1 does not work in MSVC any more. The new versions of MSDN do not
support it.

2. When you press F1, and it miraculously works, you will most
probably get help for Visual Basic, Visual FoxPro, Commerce Server,
Visio automation, Direct X, Windows CE, MFC and all sorts of other
damn interesting, but pretty useless in the context things. It is much
like Google search.

Yes Microsoft documentation definitely was not written by Shakespe. It
rather looks like being written by that famous troop of monkeys, which
should probably reach a Shakespearian quality before the Entropic
Death, or probably not. (:-))

---
Regards,
Dmitry Kazakov
www.dmitry-kazakov.de