> This isn't meant to start a war as I'm honestly looking for opinions.
> Does
> anyone find the VS help as substandard as I do (for .NET in particular).
Thanks for your feedback.
> No. Could it be improved? Sure...I've yet to see any product that
> couldn't, and that includes the docs and .NET itself.
It's still very immature in many ways. I've had at least a hundred
time-consuming problems in the past 20 months (no joke). I've posted about a
dozen of these on the MSFT Connect feedback site with one or two making it
into the first (VS2005) SP. Since my project began, I've talked with MSFT
bloggers, opened official incidents, and have generally been mired in
problems mostly related to insufficient documenation. The docs are simply
inadequate and I'm not one who needs a lot of hand-holding.
> But compared to some of the other technologies I've been using lately
> (including Apple's Cocoa and the Java environment), MSDN is light-years
> ahead. Each doc page has way more useful information, code samples are
> numerous and usually helpful, there are a number of good tutorials and
> non-reference doc pages as well, and the overall level of organization is
> much better than what I've seen elsewhere.
By comparison that's probably true but I'm not working on those platforms. I
take no solace that others are suffering more.
> You seem to be mostly ranting about the search feature, and I agree of all
> the parts of the docs it probably could use the most help. But it's
> gotten a lot better than it was when I first started using it a few years
> ago and I expect that Microsoft is as we speak working on making it even
> better (perhaps even including some of the options you're looking for).
It's not just a lack of search features (which is problematic enough), it's
the serious lack of detail and I can cite many examples both large and
small. Why must I test if a collection starts at zero (0) or one (1) for
instance and why is this inconsistent to begin with. Why must building a
"PropertyGrid" be a form of self-flagellation (due to insufficient docs).
Something even as simple as trapping keystrokes in a "UserControl" or
"Control" derivative is often an exercise in "self-control". The number of
functions for handling it is bewildering and frequently inconsistent from
control to control (with precious little documentation to explain it all).
On other fronts I can show you flagrant errors in the docs themselves
(confirmed in my dealings with MSFT), information that's missing outright
(it was either forgotten or neglected), and most of all, information that
fails to address issues that any programmer would need to know (which I'm
dealing with on a regular basis - am I supposed to figure it out via testing
or reflector?). If I had the time I could compile a very specific
laundry-list of items to demonstrate (and some MSFT insiders have privately
backed me up on some of them) but the point is that the docs need a lot of
work still. It's not just searching but the content itself is still very
weak.
Peter Duniho - 08 Jan 2008 03:43 GMT
> Thanks for your feedback.
>
>> No. Could it be improved? Sure...I've yet to see any product that
>> couldn't, and that includes the docs and .NET itself.
>
> It's still very immature in many ways.
I'm sorry...could you clarify, please? Are you really looking for
opinions? Or just the opinions that are the same as yours?
> I've had at least a hundred
> time-consuming problems in the past 20 months (no joke). I've posted
[quoted text clipped - 5 lines]
> problems mostly related to insufficient documenation. The docs are simply
> inadequate and I'm not one who needs a lot of hand-holding.
Neither am I, and frankly I haven't had the kinds of problems you seem to
have had. I've thoroughly enjoyed my experiences writing .NET programs
and have found that while there are gaps in the docs, they most often
fulfill their need. It's been years since I've had to spend any
significant time asking anyone else a question about .NET rather than find
the answer myself in the documentation.
> By comparison that's probably true but I'm not working on those
> platforms. I
> take no solace that others are suffering more.
I don't feel like I'm suffering at all, not when I'm writing .NET code.
> It's not just a lack of search features (which is problematic enough),
> it's
> the serious lack of detail and I can cite many examples both large and
> small.
.NET is an enormous API. The question isn't really how many examples you
can come up with, but rather what proportion of the total documentation
they represent. Certainly the few you mentioned, even if one accepts each
as a valid example, don't constitute a serious problem with the
documentation.
> Why must I test if a collection starts at zero (0) or one (1) for
> instance and why is this inconsistent to begin with.
You've posted to the C# and Visual C newsgroups. In C#, I've never seen a
collection that "starts at one". I don't even understand this "example".
> Why must building a
> "PropertyGrid" be a form of self-flagellation (due to insufficient docs).
That's not an example, it's a rant. What specific problem did you have
with PropertyGrid that you feel wasn't documented properly?
> Something even as simple as trapping keystrokes in a "UserControl" or
> "Control" derivative is often an exercise in "self-control". The number
> of
> functions for handling it is bewildering and frequently inconsistent from
> control to control (with precious little documentation to explain it
> all).
The only problem I've seen with this is that there are indeed a number of
different ways to trap keys. A more unified API would be nice.
But they generally break down into well-defined groups, and I've found the
docs describe these groups reasonably well (e.g. command keys, input keys,
dialog keys, etc.)
I've never had any real trouble figuring out what code to write in order
to handle a specific keystroke.
> On other fronts I can show you flagrant errors in the docs themselves
> (confirmed in my dealings with MSFT), information that's missing outright
[quoted text clipped - 3 lines]
> testing
> or reflector?).
I too have seen examples of all of the above. However, not once have they
prevented me from writing a correct .NET program, nor are they the norm.
> If I had the time I could compile a very specific
> laundry-list of items to demonstrate (and some MSFT insiders have
[quoted text clipped - 3 lines]
> work still. It's not just searching but the content itself is still very
> weak.
Well, I simply disagree. There are specific problems, no doubt. I've
noted them myself. But I'd hardly call the documentation "very weak". In
fact, I'd say that the robust documentation for .NET is one of the strong
points of the development environment.
I'm sorry you're not more appreciative of opinions that aren't aligned
with your own. I'm not interested in debating the quality of the
documentation, so if the above observations don't help you see the
documentation in a different light, consider all questions in this post to
be rhetorical. And good luck with your rants.
Pete
Alexander Nickolov - 09 Jan 2008 18:15 GMT
If you have the talent for writing, I suggest you write a book on
all those intricate little details you've discovered. Such in-depth
books a very very rare to come by, unfortunately, and the level
of detail in them is way beyond what one can reasonably expect
from _any_ documentation. The first such book that comes to mind
is Kraig Brockschmidt's "Inside OLE".

Signature
=====================================
Alexander Nickolov
Microsoft MVP [VC], MCSD
email: agnickolov@mvps.org
MVP VC FAQ: http://vcfaq.mvps.org
=====================================
> Thanks for your feedback.
>
[quoted text clipped - 44 lines]
> docs need a lot of work still. It's not just searching but the content
> itself is still very weak.