[...]
I guess what I am trying to say is that, for the newb, there are already
plenty of resources, just they might cost a little something (for the
books, under $100). The documentation is, and should be, aimed at the
more experienced users and programmers.
For what it's worth, I don't entirely agree with that philosophy, even as
I disagree with Tom's general complaint about the MSDN documentation.
Granted, I'm not a novice to Windows programming. But I was a complete
novice with respect to .NET programming, and I learned nearly everything I
know about C# and .NET either from the MSDN documentation or this
newsgroup. While this newsgroup has been invaluable, frankly the kinds of
things I learn here are usually pretty esoteric. All of the basics have
been relatively easy to pick up from the documentation. So at least to
some extent, MSDN _is_ suitable for novices, at least those of a certain
stripe.
In addition to that, my recent experiences trying to grasp the "new"
programming API for Apple's OS X operating system, Cocoa, have made me
fairly cynical about Apple's ability to usefully document their API.
Their documentation is quite poor, with very few code examples and none at
all connected directly to the doc page for specific classes in the API
(and yes, that's right...it's _one_ doc page per class, with incredibly
brief descriptions of most methods in a class). They have "user guides",
which offering tantalizing hints as to how one might do something, without
ever really putting all the pieces together in most cases (there are
exceptions, but they are few).
And note: I'm not an inexperienced Mac programmer. I have a fair amount
of experience with the pre-OS X API. But unlike the situation with .NET,
where my previous knowledge of Windows programming did help me at least a
bit to navigate the .NET API, my knowledge of the pre-OS X API was no help
at all in learning Cocoa. In many ways, the situations are very similar;
both .NET and Cocoa provide a new framework suggestive of but
fundamentally different in some ways from the earlier OS API, and in both
cases I was using a new language (C# and Objective-C respectively). But
because of the great difference in the quality of the documentation, my
experience learning .NET has been _much_ nicer than that of learning Cocoa.
Do I need the documentation to hold my hand and walk me through every
little detail? No, I agree with you that that's overkill and would
detract from the usefulness of the documentation. But the documentation
certainly should be _complete_ and should include sufficient detail so
that a complete novice, albeit a motivated one, can learn everything they
need to know about using the API from the documentation alone.
I didn't get the impression from Tom's post that he's trying to learn
general programming techniques from the MSDN documentation. I'd agree
that the documentation for a specific API like .NET or the native Win32
interface isn't the place to look for learning basic programming
concepts. But there wasn't anything in Tom's post that caused me to think
that's what he was expecting.
So, what of Tom's complaint? Well, my impression of the MSDN
documentation is that it _does_ have the potential for sparseness. And
I've seen at least one code example that is just plain awful (but if I
recall correctly where it is, they have fixed it since I last looked at it
and reported the problem to Microsoft, because what's there now doesn't
look half-bad). But I'd say that on the whole the documentation is
actually quite good. Code samples generally are complete and where they
are excerpts, there is a larger sample somewhere that has the whole
program (the excerpts generally showing up in a specific class member
page, with a link to the larger sample found on each page with an excerpt).
So while I agree with Tom that the documentation really should provide
enough detail for a novice to learn .NET, I don't agree with his
assessment that it does in fact not provide that as a general rule. It's
not perfect, but neither does it deserve the scathing review Tom's offered
here. And frankly, compared to the docs I've been reviewing recently for
other stuff, including Apple's Cocoa and the Java reference on Sun's web
site, the MSDN documentation is a breath of fresh air.
And sorry for the essay. It's just that this whole discussion brought up
some fairly painful, recent memories of my experience with trying to learn
Cocoa, and especially your comment about "the docs should be written for
the experts", which is exactly the kind of dismissal I received from the
Mac community when I made comments about how Apple's documentation was
insufficient. I didn't agree with them there, and I can't say that I
agree with you here. The big difference is that, having seen and used
both, I don't think the MSDN docs _are_ written only for the experts while
the Apple docs do in fact to be written that way.
Pete
