Some Results from Visual Studio and .NET Framework Developer Documentation Survey

Recently our documentation team hosted a survey on how you use VS and .NET Framework documentation.  Here are a few things that I thought was interesting.  I’d love to have your comments as well…  Any thoughts from you on this?


It seems that the the majority of developers in our community are using the latest (3.5) version of the .NET Framework.  Most are also using 2.0 as well…




On the question of how you would like to see .NET version information in the docs, it seems most folks want to see it all, with a filter! 

  • Documentation should be specific to the .NET Framework version I am developing with
  • Documentation should be cumulative (including all versions of the .NET Framework with version specific information inline)
  • Documentation should be cumulative (including all versions of the .NET Framework with the ability to filter on specific versions)



In terms of what folks use the docs for in their daily development, the .NET Framework reference is the winner by far! 



And how do you find information?  Well, not surprising, web search engines win out by a high margin.  Although, it does seem from the feedback that if we could improve performance of offline Help and F1 folks wouldn’t need to search online as much.  Does that seem right to you?


And, as always, the verbatim comments were very helpful as well.  Here are a couple I thought was valuable both positive and constructive:

  • Mostly good, mostly accurate, certainly better than most of the competition.
  • First let me say that the overall quality of the documentation is very, very high.  In general, Visual Studio / .NET documentation is the gold standard for technical documentation.
  • I would like to be able to specify my preferred language(s) so I do not see language examples that are not relevant to my needs.
  • I would like to see more tutorials – for new technology.   ScottGu’s blog if often a better source of information.
  • Help loads way too slowly. Pressing F1 often brings up the wrong article.   Entering a search term also brings up the wrong articles. The only way to navigate help is to use Related links, or "See also" at the bottom of each article
Comments (28)

  1. Paul Jackson says:

    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.

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

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

  4. David Nelson says:

    The first graph is interesting to me. A while back, when I reported a mistake in the 2.0 docs for Hashtable (, 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.

  5. mike johnson says:

    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.

  6. ET says:

    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.

  7. Peter says:

    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.

  8. Peter says:

    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.  

  9. Josh Stodola says:

    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.


  10. marco.chila says:

    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…

  11. Ted says:

    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.

  12. Clinton Gallagher says:

    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.

  13. Brad Dodson says:

    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.

  14. Pete says:

    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.

  15. Stefan says:

    I am a C++ developer, not .NET. I found that since the incorporation of all the language developer packages into .NET I am no longer able to find relevant information for C++ APIs!

    The help system is a total mess – even when I explicitely filter my search to Visual C++ only I keep getting swamped by articles meant for Visual Basic, C#, .NET general concern articles, ADO, WEB scripting, and so on. I do not do databases! I do not do WEB scripting! I do not do Visual Basic, C#, or .NET development, I do C++! But I do get these articles 90% of the time!

    Worst of all, in many cases when I look at an article it’s not even clear where it belongs, whether it’s a C++, C#, ADO, scripting or other article – I can only guess from the apparent style being used.

    I don’t know how people working on all these other areas get along and whether they find it equally difficult to filter on articles that relate to their own development base. Maybe they’re better of, or maybe they’ll just avoid the VS.Net search facilities alltgether?

    I suppose because of my difficulties finding appropriate offline documentation, I should be googling instead. However, since I am stuck in a tiny SW development team inside a big industrial company my access to the internet is limited. And considering how slow offline help already is, I don’t care to make it even slower by channeling it over the internet…

    All said and done, If I had a set of actual books containing all the documentation I would lose a lot less time digging for it!

  16. Kjetil says:

    I find the documentation itself quite good. The consistent layout makes it easy to find what you’re looking for, but often I find the help a little too vague or that the examples are too simple. It seems though that the later documentation is getting better (e.g. WPF). What I miss is the ability to go directly to a class’ interface or base class. For instance looking at the System.Windows.Controls.Primitives.ButtonBase, I would like to be able to go to the ICommandSource, but there is no link in the ButtonBase documentation for that.

    One thing that irritates me though, is that the “Language Filter” gets reset from time to time. Haven’t figured out exactly when it happens, but every once in a while I have to go through the list and filter out my preferred languages.

    When it comes to speed, I must agree to some of the inputs here that it certainly could have been faster. I use the online version so I expect a bit of latency, but it seems that the actually rendering of the page is a bit slow. Also; it would have been a really nice feature if I could go on the online version and choose to “download this documentation locally”. Maybe with some options of what parts of the docs to download (based on namespace and/or technology) and that the download respects my language settings (that is; don’t download any VB-content when I have checked off only C#). And the offline content should then off course always be synchronized with the online version (using some kind of background sync).

  17. Sam says:

    I’m sorry to say that VS and .NET documentation is horrible.

    F1 is SLOW!  It takes less time for me to type in a search term and get excellent, useful results that have often been reviewed (and corrected or expanded upon) by web site visitors.  F1 brings up poor search hits and the hits that at first seem like they will be useful end up being vague or missing important details.

  18. Crash2975 says:

    It takes *far* too long to load; I can open another browser session, Google for the answer and find it while waiting for this lumbering bohemoth to open up.

    I also find it difficult to find actual *useful* information and, often, meaningful examples. Many pages tell you how something is declared in four langauges and what the data types are (which you can get from Intellisense – now that is truly an excellent idea), but no indication of how it should be used or links to anything useful.

    I would describe it as "full of information, but short on knowledge".

  19. Dave S says:

    I second Mike Johnson’s comment. In general, I do find the documentation to be mostly helpful however I find that the examples are often somewhat weak & I rarely take it as gospel without first checking other sources. Codeproject is a fantastic source of information and examples, MS would do well to partner with CP to use some of the community content provided there.

    I never use Live Search any more as it’s just too slow. When I want results, I want relevant results & I want them ASAP. By far & away the majority of developers I know or have worked with use Google when they need to search MSDN.

    I also have no idea why that tree view for navigation is still there. I’d love to be able to set a preference to have it never show up again. Maybe other people find it useful but I never have. It’s the first thing I toggle when I use MSDN.

    All in all, not too bad but could most definitely be better.

  20. Owen Pellegrin says:

    <i>Although, it does seem from the feedback that if we could improve performance of offline Help and F1 folks wouldn’t need to search online as much.  Does that seem right to you?</i>

    I actually prefer offline help, but the load time is horrible.  I mitigate this by opening the documentation viewer first thing every morning, but if I press F1 it has to load a new window; the end result is I rarely use F1.

    I used to use MSDN online for documentation.  In the past, the tree view was a separate frame that was loaded once.  This was awesome, and MSDN was fast.  When MSDN switched to the "improved" layout, (with the angry, hostile red color scheme that doesn’t match the calm blue scheme of the documentation) the frame was replaced with a tree view that has to be reloaded every time.  Every. Single. Time.  The page doesn’t display until the tree view finished downloading, since it’s part of the page.  This is why, after switching from offline help to online help due to having a faster connection, I’m moving back from online help to offline help.  If I’m browsing several different members, I don’t want to wait 10-15 seconds per page.

  21. Ed says:

    The Good:

    – context sensitive help is awesome

    – index and searches are great (local)

    – agreed, even with its deficiencies, I’d take this documetation over almost any other product documentation out there. In fact, yes, I agree it’s the "gold standard" among product/packaged documentation….to be clear, I’m not saying it’s "awesome", its a comparative assessment.

    The Bad:

    While it’s easy to find the topic (local), the way its written needs work. This goes for online MSDN as well.

    When you need a separate site, i.e. ASP.NET, to make sense of documentation, well, that’s a big sign.

    On that note, why doesn’t VS help include MSDN blogs, ASP.Net blogs, forums and basically all things .Net related, coming from the source (Microsoft itself) in the search option??? As an example, Scott Guthrie’s blog is just, well, awesome. It’s proven to be more productive to start off at his blog (skip all the Google searches, etc.) to get clarity on some mind-twisting verbiage found in documentation.

    If this was a case of "the product came out first" before the blogs, then I’ve asked in the past for a way to customize the search function in VS so that users can pick/choose their "trusted content" (as additional sources only, not a replacement for local documentation).

    We all think, read and comprehend differently, so it seems to me that allowing us to pick addtional searchable content to search (instead of whatever is offered out of the box) makes sense? I mean, that what most people here are saying right? "I use Google" this and that. Why don’t you incorporate the same web search tools into VS (which you can "point" to a specific domain)? Even offer what you already know are "trusted sources"? Lke ASP.Net blogs, MSDN blogs, a host of Microsoft forums, etc.?

    Online MSDN is just a chore to use. There’s a comment above on using frames, which is right on. I personally think frames in this use is fine, but it’s just "stupid" in the way it works. That TOC refreshes on practically each link…negating the whole point of a frameset TOC – don’t you think? I’m actually assuming it’s a frameset…regardless, it needs work…in fact if its not a frameset, then think about doing so, properly.

  22. Mike Diack says:

    Is there a survey anywhere for the native code/C++ side of things? I’d love to see the comments/make comment?


  23. Tore B says:

    I find that every major change to the online help has reduced usability of it.  I attribute this to the following factors:

    1:  The amount of information has exploded along with the complexity.  I remember when developers were confounded by some 800 APIs.  But the documentation was well thought out, and mostly well documented.  It was relatively easy to find, partially because you could browse through it and learn as you did.

    2:  Microsoft has let technology drive the functionality of the online help, rather than addressing end-user functionality.

    3:  Much of the help material now appears to be auto-generated (from developer comments?) and less documentation expertise is included in formulating good documentation.

    4:  When I’m looking for something by its functionality and don’t know its name, I often find myself looking at something which sounds like it may be related, but unless I already know what it does, there is no way to figure it out from the description.  In most cases the description of a function is just a rewrite of the function name.  That is not helpful.

    5:  Examples (when available) tend to be too trivial.  A good example will avoid the completely trivial while remaining simple enough to not obscure the main points.  A good exaple may be enhanced by comments regarding special considerations (border conditions, special cases, design and developer considerations, what causes errors, etc.).  Heck, why not publish the unit tests for the function…

    7:  I tend to do unfiltered searches, but pick from the result list what seems to be the most appropriate.

    8:  I much prefer my online help to be LOCAL ONLY.  However, I don’t always upgrade my MSDN Library, so the local results will become outdated.  I would love two simple changes:

     – Provide a button that allows to check for (and download) updates to the CURRENT HELP PAGE.

     – Provide a search result button for "Check for additional search results online" which would check current result entries for updates as well as identify hits that are new.  I should then be allowed to download the new and updated articles (one/selected or all).

  24. Kent H says:

    Most points captured above.  I found the most interesting to be "use the assemblies themselves as documentation".  Why?  Because they can’t lie.

    I would argue that the #1 most frustrating thing for a developer is to code something small according to the instructions (documentation) and spend days trying to figure out why it doesn’t work because

    a)  you have no source code.

    b)  the documentation did not completely describe the behavior of the code you are trying to use.

    People may laugh, but one of the best aspects about MFC (remember that "old" framework) was that you had the source code for it, and if you coded to the doc, and it was wrong, you could at least drill into the source code to try to find the unexplained behavior.  The source code may have been poorly written or optimized to the point of incomprehensibility, but at least you could invest time and gain knowledge to use in the next design.  

    With the .NET framework, you invest time and gain opinion which then has to be tested to determine if the opinion is factual.

    And although I appreciate some assemblies having pdb files online, if they aren’t ALL available, then it is next to useless.

  25. William C says:

    Hmmm… The above comments seem to confirm that it will be surprising if you ever create documentation that makes every one happy…

    From a personal point of view While Some people may say your documentation represents a "Gold Standard" at best that would have to be a Relative comparison to the types of documentation they regularly use.

    From my point of view I find the Documentation style …. "functional" and best , generally Dry and mostly Terse , I never use it other than to clarify the syntax on a function I already know something about. It is useless to try and use it to "lean" about anything new… the most you may find is that a Certain Function may exist … then the very next thing you always do is use your favourite Search engine to find real world *Useful* examples of how to use the dam thing.

    I know that the the help manual is not meant to replace good quality books but there is a point where you wonder why a few more USEFUL examples that explain what the function do could not be incorporated.

    There are 3 basic types of information people are looking for when they look for help

    1) syntactical help

    ie they know what they want to do but they they need a memory jogger to clarify the syntax or a particular option ( a lot of this is taken care by intellisense now)

    2) Functional support

    You have a "rough" Idea of what you want to do but it is in an area that is new or unfamilia , and therefore you need help to find a method or function to do what you want togeather with a good example  of how to use it.

    ( this in my opinion is the number one reason why especially new programmers "Reinvent" functions that are already built in … they just didn’t know  a function already existed to do what they wanted. …because they couldn’t find it in the documentation )


    3)Debugging Support

    You have a problem in the code that is not doing what you thought it should be doing … once you have check that you haven’t done anything silly like passed the wrong parameter ( syntactical support above) your then stuck trying to find good examples of how the function is "Suppose" to be used and any "Gotchas" … and help from other people who want to do the same thing who have gone through the Pain of discovering that you really should be using a completly different Function to do what you want.

    … unfortunately the documentation is Usually only good for level 1 issues.

    That is not to say I have not found some very useful "Nuggets of information" but it us usually the exception not the norm.


  26. Ian Ringrose says:

    Performance of offline Help is very important, offline search should be as fast as google is.  I have enough RAM to cheep the index in money but it still seams to take for ever.

    Often there are 3 or 4 pages on a subject that mostly repeats the same information that could have been combined into a single more useful page.  It as if each page was wrote by a different person that did not have permission to change the other pages, so just wrote a new page.

  27. 【原文地址】 Some Results from Visual Studio and .NET Framework Developer Documentation Survey 【原文发表日期】 11