Home | Contact Us | FAQ | Search & Site Map | Link to Us
Sign In | Join | Other 45 Sites in Network
HomeAnnouncementsFree MagazinesWhite PapersSubmit Content
Discussion GroupsASP.NETWindows FormsLanguages.NET FrameworkVisual Studio.NET
Articles.NET FrameworkASP.NETToolsWindows Forms
.NET DirectoryOpen Source ProjectsUser GroupsWeb Resources
Related Topics
Visual Basic 6SQL ServerMS AccessOther DB ProductsMS Server ProductsMore Topics ...

.NET Forum / Languages / C# / January 2008

Tip: Looking for answers? Try searching our database.

VS online helo

Thread view: 
Enable EMail Alerts  Start New Thread
Thread rating: 
SamueL - 08 Jan 2008 01:23 GMT
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 - 08 Jan 2008 01:45 GMT
> 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 - 08 Jan 2008 03:06 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'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.
Alex Blekhman - 12 Jan 2008 14:20 GMT
> 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

Free Magazines

Get these publications absolutely FREE for up to 12 months. There are no hidden fees and no obligation. Simply choose a title, complete the application form and submit it. Read more ...

Oracle MagazineNetwork ComputingComputer WorldBio-IT WorldeWeekInformation WeekInfosecurity
 
Sign In
Join
My Latest Posts
My Monitored Threads
My Blog
My Photo Gallery
My Profile
My Homepage

Start New Thread
Enable EMail Alerts
Rate this Thread



©2008 Advenet LLC   Privacy Policy - Terms of Use
This website includes both content owned or controlled by Advenet as well as content owned or controlled by third parties.