Hello world, my name is Tim--though I also respond to TimSull, Timmy, and Timmaaayyy--I'm a developer on the Visual Studio IDE team...welcome to my blog.  I work on a number of different features of VS including Help Integration, Community Integration, Commands and Menus, Side-by-Side Versioning, and Import/Export Settings. My plan for this blog is mostly to talk about some of the cool stuff we're doing for the Whidbey release and to provide a forum for developers out there to give us feedback about our plans.  I'll try to go through my features one by one and tell what I can about our plans.  If people respond and want to know more about a particular area, I'll go into the gory details.  I must say, given that I'm still new to the whole blogging fad, I'm a bit skeptical that anybody is actually going to read my blog.  But what the heck, I'll just throw this one out there and see what happens.

 

IDE Help and Community Integration for Whidbey:

Help and Community are getting a lot of attention in Whidbey. We've received an enormous amount of feedback from customers expressing their disdain for the Help that shipped in VS 2002 and 2003.  Developers consistently complain that the help interface makes it too hard to find the help content they're looking for.  And they complain that when they finally do find 'the right topic' it's often lacking in some fundamental way.  We're trying to address these problems in a few different ways.

Improved content:

This isn't actually something that my team works on, but it's obviously really important, so I want to mention it. The editors that are responsible for writing the docs have heard your feedback and are working hard to improve the quality of the help content. For instance, C++ developers have made it clear that they don't like seeing API reference that says only 'The FooBarEx() api takes parameters int x and void *y and returns 0 if successful', with no further discussion. If documentation barely says anything more than the SDK header file, it's obviously ...umm... lacking. VB developers have told us they don't want docs that seem to be written for or by C++ developers . For the VB developers , higher level content and task based help are clearly the way to go. And virtually every developer we've ever talked to, regardless of their language of choice, has requested more and better quality code samples in topics.  All the people that are working on the help content are aware of this feedback and are working to address it in the Whidbey release.  Unfortunately, due to the sheer number of help topics in MSDN and a few scheduling and organizational issues, I can pretty much guarantee that a number of help topics will still be sub-par when we ship Whidbey. But hopefully the most important topics will have been rev'd and will be much improved.  If you've got a rant about the help content, or if you have particular topics you'd like to see fixed in Whidbey, let me know and I'll make sure the documentation teams hear your feedback.  Also, make sure to use the 'send feedback' links whenever you find an MSDN topic that's not to your liking; those bits of feedback are all read by actual people and they result in bug entries that someone will be responsible for fixing.

Improved access to content:

In VS 2002 & 2003 you have 5 ways of getting help:

  • F1 -- Completely hit or miss, sometimes it works remarkably well, sometimes it shows the Dynamic Help window which is always trying to give you help on the 'Code and Text Editor', which is never what you're looking for.
  • Table of Contents -- I don't know anyone who has successfully found a specific topic they were looking for by navigating down the TOC tree.  The TOC is most useful for finding topics that are similar or related to the current topic, using the 'Sync Contents' button on the Web toolbar.
  • Index -- If you already know the API or class name you're looking for then the Index works well, otherwise you're out of luck since this window is virtually useless for finding conceptual topics.
  • Search -- 500 results in nearly random order, choose the topic you want based on its Title and Location--unfortunately the titles are really tough to differentiate since there are lots of duplicates and similarly named topics.
  • Forgo the integrated help experience and search using the web -- Has mixed results depending on your search engine of choice, forces you to leave the IDE, which implies a mental context-switch and usually a loss in productivity.

In Whidbey we're making improvements to F1 and Search and we're adding some completely new interfaces to access help content.

  • F1 -- Better metadata on help topics will make F1 work more consistently even if you're not in the context of a project, or if you're writing code in native C++ where we usually don't have fully namespaced keywords to lookup. Better disambiguation UI will show topics that are more targeted to your selection; you won't see the same topics all the time.  You'll also have the option of going online for F1.  This will have 2 beneficial effects: First, you'll get the very newest help topics. And second, if you're not satisfied with your F1 results, you'll be able to let MS know so we can try to fix whatever bug is causing F1 to be broken.
  • Search -- Filtering will be more easily adjustable than it was in VS2002 and 2003, and will do a better job of filtering away many of the topics you'll never have an interest in. (Topics on DirectX, the Speech SDK, Commerce Server 2002, etc. might be great, but not when they show up at the top of the search results list when you're trying to learn about a TreeView control for C#.) Also, the search results will show a dynamically generated abstract based on the text of the topic to go along with the Title and Location. We hope this will make it much easier to tell if a topic will be worthwhile before you click on it and wait for the fancy script and graphics to render in the web browser window.
  • How do I... -- This is an entirely new view into the help system. It's a hierarchical organization of common tasks a developer is likely to encounter. Each developer segment (VB, C#, Web, etc.) will have its own hierarchy containing roughly 200-400 tasks. Each task will contain carefully reviewed editorial text along with sample code that can be copied and pasted into the VS editor. The documentation teams have been collecting user feedback to help determine which tasks to include in the hierarchies. If you have ideas for tasks you'd like to see in a How do I... page, let me know and I'll pass them along to the right people.  You can think of How Do I... as a hand-picked, carefully designed subset of the Table of Contents. Check out these screen shots from live builds: How Do I... hierarchy page, WinForms Controls category page.
  • Help Favorites -- previous versions of VS and MSDN contained an integrated favorites tool window, but it was just the IE favorites window, not help-specific favorites. Our initial surveys and focus groups have indicated that developers think help-specific favorites will be really useful.  People have also shown a lot of interest in the ability to save favorite search queries so they can easily go back to interesting sets of search results.

Inclusion of online content:

There are numerous things that online help can provide above and beyond what you already get with local help:

  • Smaller install size: MSDN is on the order of 2 GB when installed locally, online help has the ability to forgo that use of hard disk space.
  • Newest content: if content gets updated, the only way to get that with local help is to acquire and install one of the MSDN Quarterly updates (very heavyweight process).  With online help, you get the newest content automatically.
  • Ability to provide feedback to MS: Online help makes it easy to tell MS that a particular help topic is insufficient.

Inclusion of Community content:

Going online to access MSDN content has its benefits, but the biggest win in searching online is really the ability to access living content.  If you look at some of the fantastic work that Community-based web sites like .Net247, CodeProject, ASP.Net, and others have done, it's clear that static content published to the web can never be as rich as content that is provided by members of the developer community.  Don't get me wrong, MSDN's API reference is obviously important.  But if you open that content up to be annotated and extended by people in the community, then it becomes a much more powerful resource.  It's really a complementary relationship: MSDN content provides breadth of coverage while the Community fills in depth in the areas that are most important to developers in the real world.  Community content also helps address the need for more code snippets.  If I need help using a DataGrid control, I definitely prefer to look for code snippets at .Net 247's DataGrid page than at MSDN's static DataGrid class topic.  MSDN's code snippet looks very comprehensive, but .Net 247's page provides so much more variety, and it's directly linked to a forum where I can ask questions about the code and interact with the code authors or other forum members.  The experience at the Community-based site is much richer because the content is far more dynamic and because I can interact instead of just reading.

So how does this apply to VS?  In Whidbey we have partnered with a number of Community sites that will allow MS to aggregate and search their content from the VS client.  This means that when you search for DataGrid from Visual Studio Whidbey, you'll see a list of local help MSDN topics, a list of MSDN online topics, and a list of links to pages on CodeWise web sites.  So developers will have simple, direct access to the newest and most popular code samples and technical articles in the community.  You'll see living content alongside the comprehensive static content from MSDN.

In our focus groups, we've found that many of the more savvy developers out there currently do a 2-stage search for help content.  First they search in local help or MSDN Online, and then they search Google.  The goal of integrating community content into the VS client is two-fold: First, we want to help our not-so-savvy customers get access to all the great community content out there.  Second, we want to make finding help content a seamless experience where you only have to learn and use one UI, and you never have to leave the IDE.  The main outstanding question is: Will the quality of integrated VS search results be comparable or better than the search results from today's 2-stage search.  Because of our highly customized filtering and scoping, we think that they will, and when you combine that with having a single search entry point and a unified search results interface, our solution should be a big productivity win.

But what does it all mean (to you)?

When I look at the full list of changes we're making to improve Help in Whidbey I think they'll add up to a big productivity win for our customers.  But I'd love to hear what the developers out there think of our plans.  Are you psyched about what we're bringing to the table in Whidbey?  Do you wish we were focusing our efforts in different places?  Let us know what you think!