MS Development Nightmare: Poor Documentation

This is particularly amusing, since this is a criticism the WiNuTs often
claim about Linux:

.----
| Here is the function description on MSDN, and here is the same
| documentation on the upgraded, new MSDN2, presumably so-called
| because it takes twice as long to display (Really. MSDN-1 takes 8-10
| seconds here, versus 15-20 seconds for MSDN2, depending on time of
| day.
|
| ...
|
| How about this: because LockWindowUpdate is entirely typical of MSDN.
| The whole, bloated thing is jam-packed with function descriptions
| that tell you everything about the function except what you need to
| know, huge, dull, explaining-by-not-explaining articles extracted
| like rotten teeth from MSDN Magazine and its predecessor MSJ, and
| filled with bogus enthusiasm for, say, this month's approved way of
| interfacing to databases.
`----

Roy Schestowitz...

GNUgle to the rescue. From the above:

,----[ Quote ]
| Then there are the dreadful, slow searches, compulsory in the CD-ROM
| only days, now happily alleviated by web-search (What is it about
| Microsoft and indexed searchable text? They always seem to get
| it badly wrong: think Windows Search, think those old help file
| indexes that always needed rebuilding). And why the almost
| complete absence of pictures? This is, after all, supposed to
| be the documentation for a graphical operating system.
`----

They must be running MSDN2 on Vista.

BearItAll...

The idea of MSDN was always a good one, many of the functions (and then
later classes) were well documented and in many cases the three line sample
code was really all that you needed to successfully incorporate the
function or event in your own code. I used MSDN mainly with asm but I found
it extremely usefull when I was dragged kicking and screaming from my
beloved asm to dreaded C (I didn't want to be a C programmer, and anyway I
didn't think it would last). I can't think when MSDN first turned up, I
remember receiving a set of 5 1/2"floppies that just contained many
examples of code.

The problem with it was with some particular areas, probably what we can
call the more difficult areas, it is a while now so I can't really remember
specific examples, where you felt that the three line example was very
necessary because the function (or class) did not really give a full enough
description to make good use of it. Then going through MSDN, in the days
when I paid for it, you got the feeling that people were deliberately
avoiding these more difficult areas, because they would be no comments, no
snippets of example code and so on. Ask a question related to the area
'Does anyone know how you make safe use of foo.c?' and you got the chat
equivelant of blank stares.

But then we in Linux world can't really claim to do a better job. The
standard libs are well documented of cause, but additional libs often are
very lacking in this area.

[H]omer...

However, the Windows GDI is about as central to that OS as you can get,
unlike the rather peripheral elements of Linux that you mention.

Have a go at using Mono, see how far you get before you start hitting the
'Document not yet writen' texts. Even basic controls you have to guess
parameters, members, events.

[H]omer...

Frankly I think Mono is just an unnecessary concession to Microsoft, so
it really doesn't surprise me it is poorly documented. It certainly
isn't a core element of Linux, and I sincerely hope it never will be.

I do like the php documentation system. It is very easy to follow easy to
find a relevant class or function to what you are doing. Well named classes
so you can easily see related areas. Even less used areas are well
documented. It would be nice to see that sort of approach adopted for the
Linux libs and additional vendor libs.

[H]omer...

My experiences have been very positive WRT Linux documentation, However,
there are two exceptions I can think of:

1. RPM. Until fairly recently the documentation for RPM was horribly
outdated, and gaining insight into the black arts of RPM package
building required joining the mailing list of the same name on Red Hat.
I'm sorry to say that I learned everything I know about RPM the hard
way, but the cat-calls from myself and others did eventually embarrass
RH into publishing an update ... albeit too late, in my case.

2. ffmpeg. IMHO ffmpeg is probably the best media transcoder anywhere on
any platform, by a huge margin. However, the developers commit sweeping
changes on a seemingly daily basis, that not only break backwards
compatibility with e.g. command flags, but (even more unforgivably)
these changes are completely undocumented ... anywhere. Once again, the
only way to ascertain the nature of these changes is to join the mailing
list.

Now one could argue that, although ffmpeg is not a central element of
Linux, certainly RPM is (unless one is using a deb distro, or Gentoo,
Slackware, etc.). However, outdated though it was, RPM documentation was
mostly complete, accurate, easy to follow, not misleading, and widely
available. And of course, a few pertinent questions on the mailing list
usually filled in the blanks.

From what I've seen of Windows API programming, most of it seems like
pure guesswork, with most programmers referring to equally uniformed
peers for answers they cannot give. As we see from the above example,
the vast majority of these programmers simply reuse methods that each
believes must be correct, in the absence of any definitive guidance from
Microsoft. The salt in the wound is that these people then have to pay a
sometimes hefty sum for the privilege.

Now I'm not saying that *I've* never referred to peers for programming
guidance, but when I have, I have invariably been directed upstream to
the actual developers, who are more than happy to not only provide
documentation, but equally happy to just chat. And the only "payment"
transaction that takes place, is in the form of whatever code I
contribute back into that project. This is, IMHO, exactly what software
engineering *should* be.

Oops, no - looks like it's actually Win2K3 (DFS won't be happy).

It explains the trend though, as Microsoft's documentation gets worse,
so does their software, with Vista currently being their worst yet.

Roy Schestowitz...

Even microsoft-watch has left the boat.

The Dog House 205 Main St Collins IA US 50055 72.32.70.141 Linux
Apache/2.0.52 Red Hat 3-Nov-2006
The Dog House 205 Main St Collins IA US 50055 72.32.70.141 Linux
Apache/2.0.52 Red Hat 1-Nov-2006
UUNET Technologies, Inc. 22001 Loudoun County Parkway Ashburn VA US 20147
63.87.252.160 Windows 2000 Microsoft-IIS/5.0 3-Sep-2006
UUNET Technologies, Inc. 22001 Loudoun County Parkway Ashburn VA US 20147
63.87.252.160 Windows 2000 Microsoft-IIS/5.0 4-Jun-2006
UUNET Technologies, Inc. 22001 Loudoun County Parkway Ashburn VA US 20147
63.87.252.160 Windows 2000 Microsoft-IIS/5.0 9-Aug-2005
UUNET Technologies, Inc. 22001 Loudoun County Parkway Ashburn VA US 20147
63.87.252.160 Windows 2000 unknown 8-Aug-2005
UUNET Technologies, Inc. 22001 Loudoun County Parkway Ashburn VA US 20147
63.87.252.160 Windows 2000 Microsoft-IIS/5.0 28-May-2005
UUNET Technologies, Inc. 22001 Loudoun County Parkway Ashburn VA US 20147
63.87.252.160 unknown Microsoft-IIS/5.0 27-May-2005
UUNET Technologies, Inc. 22001 Loudoun County Parkway Ashburn VA US 20147
63.87.252.160 Windows 2000 Microsoft-IIS/5.0 8-May-2004
RealNames Corp 150 Shoreline Drive San Mateo, CA 94065 US 63.87.252.160
Windows 2000 Microsoft-IIS/5.0 14-Feb-2003