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

• Anonymous
  August 11, 2008
  PingBack from http://hoursfunnywallpaper.cn/?p=822

• Anonymous
  August 11, 2008
  The comment has been removed

• Anonymous
  August 12, 2008
  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.

• Anonymous
  August 12, 2008
  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

• Anonymous
  August 12, 2008
  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.

• Anonymous
  August 12, 2008
  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.

• Anonymous
  August 12, 2008
  The comment has been removed

• Anonymous
  August 12, 2008
  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.

• Anonymous
  August 12, 2008
  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.  

• Anonymous
  August 12, 2008
  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...

• Anonymous
  August 12, 2008
  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...

• Anonymous
  August 12, 2008
  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.

• Anonymous
  August 12, 2008
  The comment has been removed

• Anonymous
  August 12, 2008
  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.

• Anonymous
  August 12, 2008
  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.

• Anonymous
  August 12, 2008
  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!

• Anonymous
  August 12, 2008
  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).

• Anonymous
  August 12, 2008
  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.

• Anonymous
  August 13, 2008
  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".

• Anonymous
  August 13, 2008
  The comment has been removed

• Anonymous
  August 13, 2008
  <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.

• Anonymous
  August 13, 2008
  The comment has been removed

• Anonymous
  August 13, 2008
  Is there a survey anywhere for the native code/C++ side of things? I'd love to see the comments/make comment? Mike

• Anonymous
  August 13, 2008
  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).

• Anonymous
  August 13, 2008
  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.

• Anonymous
  August 13, 2008
  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 ) and 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. William

• Anonymous
  August 13, 2008
  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.

• Anonymous
  September 07, 2008
  【原文地址】 Some Results from Visual Studio and .NET Framework Developer Documentation Survey 【原文发表日期】 11