PingBack from http://hoursfunnywallpaper.cn/?p=822

Another form of documentation that should not be overlooked are the assemblies themselves. I use Lutz Roeder's Reflector as my first port of call to find out about a managed API or simply to see how something works.

After that I'll look on MSDN about that API by using the menu option in Reflector. Only then, if that approach, fails will I resort to using a search engine; typically Google.

I tend to work with new/beta technologies in my line of work, so there is generally little useful documentation written at that point, so the assemblies speak volumes (Silverlight 2 beta 2 is great example - I'm currently writing course ware for Silverlight 2 and what the docs say is what should be rather than what is - the assemblies never lie!)

I hope this helps.

I just want to put out there that the current way the framework/Visual Studio documentation is organized, with the version links in the upper right hand corner legend is awesome.  It's really nice to find something from 2.0/2005 and be able to jump directly to the 3.5/2008 version.

My latest in a series of the weekly, or more often, summary of interesting links I come across related to Visual Studio. Yesterday, Visual Studio 2008 SP1 and .Net 3.5 SP1 were released. Below is a list of links related to those releases: Greg Duncan

The first graph is interesting to me. A while back, when I reported a mistake in the 2.0 docs for Hashtable (https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=269447), I was told that the 2.0 docs were being deprecated and replaced by the 3.0 docs. While that makes some sense (since everything in 2.0 is exactly the same in 3.0, which makes no sense at all), apparently it never happened, since lots of people are still using the 2.0 docs. I think this underlines a point I made in the discussion of that bug report: even though you could theoretically deprecate the 2.0 docs in favor of 3.0, most people don't think of themselves as using 3.0, and therefore don't think that the 3.0 docs apply to them.

it seems that the local help is very, very slow. when the web search returns results before local help, the local help is of no use. after a while, one defaults to just having a browser open to live search or google and running the help search from that search facility.

ps. to make make matters worse, I find that google does a better job of finding and getting me to things at the microsoft site better than "native" web search facilities provided by MS for its own site. ouch.

I'd say that I *like* the the version switch in the top right corner, I'm glad it's there, but I do wish for something that would be better (but unlikely to happen):

 Let me see what changed between the versions.

For example, if I'm looking at the 3.5 docs (because it's the default) and the method I'm looking at hasn't changed since 1.1, then the links for 2.0 and 3.0 should be 'greyed out' or give some other hint that there has been a behavior change.

Ideally the member list (when viewing in 3.5 mode) would have little 'new in 2.0', 'new in 3.0' indicators to let me get an idea of what the scope of changes was.

I say this knowing it may be a massive effort and unlikely to happen, but I consider it the best practice to look at the current docs (3.5) as I go, but able to see where I'm breaking compatibility.

My background is that I am developing a 2.0 application. The 3.5 redist is too huge and the client profile doesn't look to solve the issue for our needs, but I still like to know what is going on.

The coutnerexample is how Win32 documentation is done on MSDN. It is absolutely horrible to fidn a function that does what you want to do via PInvoke, code it, test it, then after the fact realise tha tyou missed a tiny note about compatibility at the bottom of the page saying 'Windows Vista'. And all your XP testers smack you on the head. I know it's my fault not checkign the dependencies, but I do feel the Win32 docs minimize the imporatance of compatibility; with the .Net style I propose I would see on the top right which platforms are supported quickly and easily.

Whoever said that the Microsoft docs are the "gold standard" is a moron. Microsoft documentation is consistently both verbose and vague, with a large dollop of just plain wrong.

While I'm am it -- who came up with the graph of which versions people use?  And why in the world would they split the "3.5+20" people from the "3.5+3.0+2.0" people?  Is there any use to that distinction?

Once you make that change, it become clear that the overwhelming majority of users

(a) use 3.5

(b) use earlier versions too

They way you have it presented, you just know that you have a big mismash.  

I really wish you would reply to my email with regards to VS2008 performance on XP 64-bit.  If your reply bounces back, please send as plain text.

Regards...

That's true... to find some help within MS search is worst then to find out with Google. Almost always I reach to a  link inside MS going thru Google because searching from MS does not find what I was looking for...

Please consolidate the documentation in the following way:

Put all articles for a specific .NET api call on the same page with the most recent docuemnation version listed first and then older versions listed at the botton in reverse order.  

Too often, the documentat has mulitple pages for the same topic each for a different product version which means that you a) cannot find the docuemtnation for the particualr version you are interested in and b) the documentation for the most recent version generally is less complete than the older versions

I second the comment on how the existing supported .NET version documetation get ignored when a new .NET version is released or just about ready to be released.  Please update the older doucmentation and not let it stagnate.  This is why we want all of the docuemtaion for the same API call on the same page for different .NET framework versions.

Lastly and most importantly, the newest version of the .NET framework documentation needs to be much more than than the ouput of the function headers (e.g., like reflector and ndoc).  This includes good sample code also.

MSDN has turned into barely usable trash; granted all of the documents not being loaded will some day a year or so be found once again eh?

Let's not forget the foolish use of framesets which break page zoom and impose horizontal scrolling. The decision to deploy framesets has proven stupifying.

The way help now functions with VS2008 is convoluted and rarely expedient.

All in all from my perspective documentation is very very disappointing having made what was once actually quite decent and at least tolerable into what? GFS and FUBAR comes to mind when the deciding factor is usability.

MSDN is mostly pretty good. Takes some getting used to vs. say Java's documentation. It would be nice if you had a streamlined version (no images, etc) that loaded much faster. Overall the documentation has improved dramatically I think. I especially like having examples that actually show the key features (i.e. are not totally trivial). I feel like you should expand the info on classes to highlight which members are useful for which purposes so I don't have to click through to a bunch of pages for the class members to find the one I want (ofthen I find the remarks section of pages to be the most useful by far - perhaps you should move it up on the page).

Possibly you can make collapsing a section for a language in the page actually uncheck that option in the language filter so that it'll "just work" for more people.

Also - one of the more anying things in .net is when you have a class that has a property which is some custom struct (delegate, event, enum, etc.), so that to get to the info i'm interested in (say for example, which flag i want to set) I end up having to click through like 7 pages (search for the class in live search, click the class page, go to it's members, property, that type's definition... you get the picture). If it would just excerpt from the other page (perhaps make it ajaxy?) that would save a lot of trouble I think.

Anyhow, keep up the good work.

Remember the days when you pressed F1, and context-sensitive help appeared within 1 second within the visual studio window?  Why can't we have that back?  That was helpful.