VS online helo

[SamueL]

Hi there,

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). I
don't understand MSFT. Today's documentation is worse than what VC6 offered.
Whenever I run a search (Ctrl+Alt+F3) for instance, I almost never find what
I'm looking for. In fact, most of the time the topics that come up are
irrelevant. You can't search previous search results (why on earth was this
removed), wildcards are no longer supported, etc. What they do give us (the
ability to confine a search to "Language", "Technology" and "Content "Type")
is almost useless given how broad the topics listed here are (the latter two
in particular). It almost never improves the search results. Even the "Index
Results" can be incredibly annoying. If I type "Control class" in the "Look
for" edit box for instance and then press <Enter>, the "Index Results"
window that shows up at the bottom currently displays three (3) different
versions of this class in VS2008 (for "presentation framework", "system.web"
and "system.windows.forms" - the situation is basically the same in VS2005).
You then have to pick one even though the first in the list shows up in the
top (main) window automatically (which is incredibly irritating since I
didn't explicitly pick it and it's almost always the wrong one). This occurs
for many different classes but in reality most people are only working with
one of these technologies at a time. Would it have been so difficult to
provide an option to always pick the one we're working with and bring it up
(say, "system.windows.forms"). And what about case-sensitve searches and
regular searching in general. These are technical documents after all and
they frequently require a high-degree of search precision. Lastly, and by
far the worst problem, the amount of information provided for many .NET
classes is woefully inadequate to get the job done. I almost always have to
augment the information by conducting painful web searches when MSDN should
have been the definitive source. It's also dangerous to trust anyone outside
of MSFT and nobody should have to. In fact, I calculate (without
exaggeration) that the program I've been working on for the past 20 months
(now winding down at last) has literally taken 50% longer than the
(WinAPI-based) C++ programs I used to work on (on a proportional basis).
It's caused no end of grief and frustration and it's mostly been due to a
serious lack of documentation. If MSFT doesn't realize how serious the
problem is then they should take some advice from someone who's been working
on their platforms since the XT. I don't normally denigrate MSFT (just the
opposite in fact), but the docs are in serious need of a major overhaul.
Tell me I'm not the only one who's suffering with these problems? End rant.

 

[Peter Duniho]

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

No. Could it be improved? Sure...I've yet to see any product that
couldn't, and that includes the docs and .NET itself.

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.

The Apple OS docs are a particularly great example of bare-bones,
practically-useless documentation IMHO. They have just a single doc page
for each class in their Cocoa framework, and most functions get just one
or two sentences purporting to describe the function. A handful of
classes get a broader description of the class and how to use it, but it
turns out that the level of detail is usually still insufficient even in
that case (Apple has correctly identified the complicated classes that
merit more discussion, but they've provided only the level of discussion
that _every_ class should get but doesn't, without providing the
additional detail the more complicated class merits).

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

Pete

 

[SamueL]

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]

Thanks for your feedback.


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

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
(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?).

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

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]

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

--
=====================================
Alexander Nickolov
Microsoft MVP [VC], MCSD
email: (e-mail address removed)
MVP VC FAQ: http://vcfaq.mvps.org
=====================================

 

[Alex Blekhman]

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

I feel your pain. Several recent releases of MSDN library made an
ipression of half baked product. I understand that the volume of
information grew tremendously lately. It seems that the library
undergoes some serious rearrangements right now and they try to
stabilize it. Also, MS tries to line up its help system, so
several products would be able to integrate their documentation
with common centralized repository.

Meanwhile I try to learn my way through the library. Also, MS
blogs are great help. I wouldn't be able to accomplish several
task in my .NET project without MS bloggers. I think many of these
posts should be added to MSDN library.

However, I agree with you. Recently I made a little .NET project
just for fun in order to learn the C# language and .NET framework.
While MSDN provided good overview articles and bnasic examples, I
would be helpless without Usenet and Google. When the project was
finished I already had used to search with Google first without
even opening MSDN.

Alex