Welcome to MSDN Blogs Sign in | Join | Help

Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

We heard you, and if you heard a loud cry of joy from the Pacific Northwest around the middle of December, you may have heard me! 

I'm thrilled to report that Microsoft's Server and Tools Business has decided to invest in significantly improving the Developer and ITPro help experience over the upcoming years!  A new small team of engineers will soon be on the job of raising the bar for the experience of installing, using and updating documentation for Visual Studio, MSDN and other products!  What's at the top of the priority list? Making your F1 and search experience fast and relevant.  Once we solve that we hope to offer you a simple viewer and update model to keep you in the know and highly productive.

What say you!?  What is important to you? What would you like to see? Remember that question I posed to you nearly a year ago - what is your dream assistance scenario!?!?!?  After we fix F1 and search, what is most important to you?

If we nail Search, do you still need the Index? Will intellitype in the search box do or do you really want that separate window?

Keep your eye on my blog, because we'll be looking to you for feedback on our many ideas and plans for improving your ability to get the answers you need - FAST.

 aprilr

Published Monday, January 28, 2008 4:28 PM by AprilR
Filed under:

Comment Notification

If you would like to receive an email when updates are made to this post, please register here

Subscribe to this post's comments using RSS

Comments

Tuesday, January 29, 2008 1:22 PM by Kathleen's Weblog

# Improvements to Visual Studio Help

The top customer requests from the Visual Studio Content Survey are to improve search and F1. Well, improvements

Tuesday, January 29, 2008 1:57 PM by Michael Giagnocavo

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

I use the index almost exclusively. The search would have to get several orders of magnitude better than it is for it to replace anything.

My personal pet peeve is the annoying VB-specific nonsense spread throughout things. For instance, the index lists generic types twice, once with C# and once with VB syntax. Also there are all these notes and so on, "Nothing in Visual Basic" and "VB Users can use the AddressOf keyword .. something about delegates". Does that REALLY belong in the reference to a library?

Tuesday, January 29, 2008 2:19 PM by Noticias externas

# Improvements to Visual Studio Help

The top customer requests from the Visual Studio Content Survey are to improve search and F1. Well, improvements

Wednesday, January 30, 2008 3:56 AM by davidacoder

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

Thank you so much for picking this up!!! This is really neede badly.

One small thing: Make the mouse wheel always work, i.e. scroll whatever is under the mouse when I turn the wheel :)

Wednesday, January 30, 2008 5:31 AM by Tim

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

It's great to see MS acknowledging that help is very badly broken in VS.  I get the impression that the challenges in accomplishing this at all have thus far overwhelmed any chance of doing it well.

My own experience was that out of the box on a 2GHz/Dual Core 2G RAM development machine, I waited 55 seconds for F1 to deliver help for the first time in the original RTM VS2005.  Sure it got a little bit quicker after that and there were ways to tweak it, but coming from another IDE where help was pretty much instant, it was a rude awakening.

I would set an absolute ceiling of 100ms for help to show after pressing F1.  My Borland C++ ID of 1991 on a 33Mhz laptop took 500Ms max to deliver help.  Surely we can improve on that, if only a little.

How would I go about achieving this?

1) Always install *everything* locally.

2) After I press F1 *always* load local help first.  This should be basic info (perhaps not much more than intellisense ) with links to related extended topics, weighted (ie which technologies are shown first) by my current development context and personal search history.

3) Once help is up, go online and check for updated content.  Where updated inline content is available, *unobtrusively* highlight this (eg using the gutter as per changed source in VS).  Let me choose whether I want to view the updated page, but download it for me in the meantime.  Where new links are available, add these at the bottom.  You can still weight these with visual cues, eg bigger text links are those more relevant to my personal search history,  brighter links indicate those articles highly rated by the community.

Wednesday, January 30, 2008 10:51 AM by Balboos HaGadol

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

Relevant help - and stop forsaking C++ !  Surely, someone at Microsoft is clever enough a programmer to give C++ examples?

I use the Index search for nearly 100% of my needs.  Unlike search, I can see a broader picture of the related items nearby in the index.

The quality of the help never ceases to amaze me!  When I first started using VS2003's SQL.NET classes, I used the ExecuteScaler() call.  I was having trouble getting used to how to map its return value type to my data type (remember, I was new in this managed environment).  I found the example all right.  The problem was, the genius (read: moron) who made it called GetScaler() but never mapped the value to a symbol - as though it returned to type void.  This is not atypical of my experience.

Another was using  Interoperability in order to access the spell checker.  I had to use a great deal of intuition in determining what I should put into roughly 17 argument required for the C++ version: no example given and the VB/C# version apparently had overloads to avoid this.  

The countless hours spent . . . well that is why this blog is here, isn't it?

Let's not forget the circular link-references, either!  Often, following the promising links returns you to the start in about three steps.

So - never mind the spurious hits - make the ones we get relevant and intelligeble!

Wednesday, January 30, 2008 2:45 PM by Koro

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

Integrate help for the functions into IntelliSense. That is, when the yellow popup pops up with the function definitions, make it have little '+' for every parameter to know it's meaning (and, if the parameter is a struct, another '+' to see it's documentation). A little like the debugger does to inspect values in VS2005.

Thursday, January 31, 2008 6:09 AM by Legolas

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

What is important to me is an easy way to make the difference in a search between language help (what does printf do), technology help (how does IIS do ...) and Visual studio-C++ help (how do I remove a configuration from a project in Visual C++).

Currently (vc2003) I'm looking for "remove project configuration", filtered by "Visual C++", and I'm getting "Enterprise templates: building an Application Construction Kit" as first item, then "Walkthrough: Creating a New Enterprise Template", "Removing, Deleting, and Excluding Items" (the first one that could have been relevant for those terms for me).

Oh, and I myself could do with a bit more clarity on the "visual studio" term. What is that exactly? (How do I start it, and what language does it edit/compile/whatever? ;-) Or is Visual C++ an instance of "visual studio"? Or is "Visual Studio" all the Visual stuff together? If I'm searching with the "Visual Studio" filter, will I get help only for things common to all Visual studio components? Or anything from any Visual studio component??

(Then again, even google does not know how to "delete project configuration visual c++"... I guess I'll just edit the project file.)

Saturday, February 02, 2008 2:23 PM by alex

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

I think you are addressing the wrong problem. No doubt MSDN is broken, Visual studio is in the bad shape, but you are trying to address individual problems instead of going for the root of them all. This very page accidentally has links (on the left) to  C++ team(http://blogs.msdn.com/aprilr/archive/tags/C_2B002B00_+Team/default.aspx) and MSDN search team (http://blogs.msdn.com/msdnsearchblog/) blogs. First go to MSDN team's link "...We shipped a new version ... influenced heavily by YOU! ..." First item of the release is integration with Live search. Influenced by us , REALLY? I have hard time to believe this relaease is influenced by anybody, but Microsoft marketing. Now go to C++ one - you will not find mention of any real problems there , just some baby talk on How exciting that or this new cool feature is ... I think you should change you developer's attitude first, making sure that your developers understand that you DO HAVE A PROBLEM with you VS product line. After that you can go and fix individual problem. P.S. it seems like your developers have way too much time on there hands if the team blog pages maintained better than actual MSDN.

Monday, February 04, 2008 3:46 PM by David

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

As a programmer who has been using Visual Studio since version 5, I feel your pain.  The current state of the product is beginning to make me re-consider my investment in the MSDN library.  Why sink money into something when Google delivers better content than the product you invested money in?  I am beginning to think spending money on retail copies of software is a better choice every few years.

Besides the obvious reasons, why are you considering using Windows “LIVE” as your method of delivery?  Entering the same search phrase into Windows “LIVE” and Google produces completely different results.  Google delivers content (or a way to find what I am looking for) within the first two pages (at worst).  Windows “LIVE” delivers useful content (if it does at all) on the 5th or 6th page.  Tying your product to a single vendor seems to be a bad choice.  If I am forced to integrate windows desktop search to use your product I will choose anything else.

While making “F1” work again is a laudable goal, why not work on using user preferences?  I dislike it when I select “use local only” and the help system goes online anyway despite my preselected choice.

I would suggest allowing the end user to hide content that he does not wish.  An annoying feature of the current system manifests itself when you select “C#” as your search content but are shown Office content.  Perhaps a “more matches available” link would be a good idea.

Thank you for being frank in your video blog.  You have a large task ahead of you.

Tuesday, February 05, 2008 9:20 AM by Robert S. Robbins

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

I make extensive use of Help 2.0 to integrate my personal notes into the Microsoft Document Explorer as a custom help collection. The time consuming process of updating help is really annoying because I update my notes every day. I think you should make it easier for developers to annotate the documentation and make it their own. I would love to add sticky notes, code examples, and other material to the MSDN collection. I've been very innovative with my custom help collection which even includes some AJAX style web applications. Some technical issues I've worked around include; CSS background images (Help 2.0 has difficulties finding images referenced in CSS), and the XMLHttpRequest object encounters cross domain request restiction issues because of the peculiar protocol "ms-help://".

Tuesday, February 05, 2008 12:00 PM by Ed

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

That was a great interview! I'm not one who will "blast" Help and will only say that yes, it does need improvement.

Yes, I also do searches online using Google and/or Live or Yahoo - but it's really more about finding someone else's take on the documentation itself. In other words, it's not finding the documentation, rather, it's understanding it a little bit better (than how it's written).

In the end, I've come to trust the various MSDN/ASP.Net Blog sites, and if there was one worth mentioning here, it's Scott Guthrie's blog.

So aside from focusing on just the "architecture" (re: the underlying technology) of the help itself, and to avoid a total rebuild, maybe links to "official" blog posts become part of the documentation itself.

I'm sure there are many reasons why people end up searching the web for guidance instead of the local help, I'm sure more practical uses are one of them (trusted peers, etc.). Sometimes documentation needs "interpretation" to real world use....

Tuesday, February 05, 2008 4:16 PM by Ian Boyd

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

i loved chm. Do what that did. If html is a security risk then just keep the interface.

Never get rid of the index. Having some poor soul go through all the content to detail for you the specific document that deals with a particular topic is invaluable.

Having the indexed list that points you to the page for each concept is invaluable.

For example: SQL 2005 BoL, search for "as"

Local Help (1)

  EXECUTE AS

MSDN Online (100)

  as (C#)

  Sub SetBasicProperties(

  as (C# Reference)

  new (C#)

  Event OnClickIndicator

  Writing a DataSet as XML Data

  ...

As opposed to searching the index:

  AS clause

Searching isn't good as a reference. That's what the index and table of contents are for.

Do what HTML Help did. Table of Contents, Index, Search. Fast. Favorites that are not part of my ie favorites (who's idea was that??). Search results in a left pane, so there is more vertical space to see the results, each of which are one row high. CHM is FAST. Click, page. Click, page.

If CHM was security error prone, then just fix it.

Did i mention fast? Fast index seeks. Fast searches. Fast navigation.

Wednesday, February 06, 2008 3:12 AM by AprilR

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

Hi everyone!  Thank you for taking time to type in your thoughts here - I read all of it, and the new team will benefit.  Keep the comments coming, and stay tuned!

Oh, by the way, the C++ links on my blog are there very much on purpose - earlier posts on my blog were from my time with the C++ team (nearly 8 years!)....and I will always be doing what I can to make sure C++ devs docs are on par with the rest....a little piece of my heart belongs to C++ :D

- AprilR

Thursday, February 07, 2008 6:28 PM by William Vaughn

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

I spent five years on the Visual Basic User Education team and wrote a considerable number of topics on data access issues. Back then we could leverage the Programmer’s Guide books (you know, those things with paper pages). Just before I left the team was assimilated by the Microsoft global help engine. Suddenly, we were asked to make topics less Visual Basic Vx-specific and shorter—far shorter. When I turned in topics that discussed how to best connect to SQL Server they were rejected—“too Microsoft specific” I was told. “Make them generic so as not to disenfranchise the Oracle, Access/JET or any other DBMS vendor. At that point I was ready to quit—and I did.

I think help has improved in Visual Studio 2008 to some extent. At least when I type Dim in Visual Basic and press F1 I’m taken to the right topic. But all too often I too have to use the index to find what I need. As I’ve said before, the help system needs more help. That is, it needs to know the context in which to search when locating topics. Is the developer working in Visual Basic.NET, Visual Basic Scripting, Visual Basic 6.0, VBA or one of the other variations? Why is it that we still have to use Google to find the most relevant technical information? Of course the elephant in the tent is that the Google engine is vastly superior to the search engine used by Microsoft—the one it steadfastly supports even though it’s not the best choice for developers.

As good as you make the content, if they can’t be located in a timely fashion without dozens of duplicate entries returned, without irrelevant content being returned then you might as well keep the old help system. Developers need a way to say “I want X with Y but not in Z, Z1, Z3 or Z4”. Help us help Help. Let us refine the query by selecting items that are not relevant. Help should be heuristic so it learns what the developer is doing and is likely to need.

Yes, Help needs to be faster. Load faster, find faster and find more efficiently. The fastest of the help engines is useless (and a waste of time) if it returns the wrong, irrelevant or incomplete information.

Bring back Programmer’s Guides—even if you have to hire these out. No, I’m beyond volunteering for this project—but I applaud it.

Tuesday, February 19, 2008 1:51 PM by Somebody

# Split Help viewer and MSDN content from .NET SDK

Please split the help viewer and the help contents from the .NET SDK or make them at least available separately.

So for somebody not wanting to do .NET development the content and the viewer could still be relevant/important and he could save quite some space on the harddrive by not also installing .NET SDK stuff he wouldn't use anyway.

Maybe even split the help contents into several packages:

- C#

- VB.NET

- C++

- WinAPI

and make them installable seperately.

Monday, April 14, 2008 1:27 PM by arnshea

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

One thing I'd like to see added to help is an easy way to send something from the documentation to another person.

I personally love help; the main reason I switched to 2 monitors was to have local MSDN docs open all the time.  I have 3 local versions of MSDN installed (and open) right now; 2001, 2003 and 2005.

Unfortunately, pretty much everywhere I've worked I'm the only one to use the local help.

However, I DO find that people WILL use help when it's sent to them (and the email isn't too long).  This is especially true if the email has a short code snippet.  

I also find that people use MSDN online if a google search happens to link to it since a lot of developers use google as a first resort when they encounter a problem.

VS2005 has a wonderful feature of allowing searches of local, online and other information stores.  I've taken to finding a result locally, switching to the online tab, then emailing the link to the online result to coworkers.

There's a learning curve to MSDN but it might be reduced with a short, interactive "Help Tutorial" included in the local help.  The tutorial could be interspersed with a few question/answer pages that guide the user through finding an answer in the Help documentation.

It might also be helpful to copy the "related links" section to the top of any given help page.  If the page doesn't answer the user's question they're made aware of other possible.  This is one of those cases where redundancy can be a good thing even if it requires care to maintain the duplication.

Speaking of redundancy, it might also be helpful to err on the side of duplication.  As developers we usually try to avoid duplication as much as possible, for good reasons, but when it comes to help the maintenance/referential integrity concerns should be balanced against the ease of finding what the user is looking for (even if they can find it in 3 places).

I don't know of a good way to say this but I wish help didn't include exotic/atypical hardware helpsets by default.  I've seen many skilled developers give up on local help because their search for an API call resulted in 25 Windows CE matches before the first non-WinCE match.

Lastly, I think search should default to narrowly searching for the terms the user typed while offering the stemming/related words/corrected spelling alternatives at the top of the page (ala google's "did you mean ...?").  500 search results returned because of auto inclusion of related words is a real pain; it's the first thing I turn off when I use help.

Another thing - it would be great if the local help's search could be improved by the usage of online help.  e.g., if certain documents have a high click through rate for a given search then they would be weighted more heavily in search results.  Even better would be to heavily weight those documents where the user searches, clicks a link to the document and has a gap in session activity (which indicates it was a good match).  Either way, feedback between the offline and online help could improve help...

Thursday, June 12, 2008 2:16 PM by jpournelle

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

As documentation manager for an SDK manufacturer, I hear it all. Here's what I hear most:

1. Load time. PLEASE speed up help load.

2. Wildcard Searches. Please! And yes, keep Contents and Index tabs. There's no way to please everyone with any one strategy.

3. Mechanism for us to add our own webhelp as an online fallback option for failed links and searches.

We manufacture multiple products, and our help is heavily cross-referenced. If a customer does not have all modules installed, we need a way for "failed" links and local searches to fall back to our online webhelp (just as it does for online MSDN documentation). We can provide a lookup table that matches ms: links to http: links, or you can give us a default link syntax.

Friday, December 12, 2008 6:51 AM by Aaron

# re: Help is Getting Help - The Long Overdue Makeover for Visual Studio and MSDN Help

Having taken on the job of writing an HTML-Help-alike application for OS/2 to replace IBM's ancient monstrosity, I have some opinions...

1) CHM was/is near perfect. It's fast, focussed, and has just enough features (except for leaving out forward button by default :)

2) Everything since has been a bloated mess, with it's own bizarre UI conventions and attempts to be "more webby".

3) Index is a great tool for those who know what they are looknig for. In SDK docs, you know there will be a topic with the title of the keyword/API, so searching in the index is the quickest way.

- in more general purpose help, which isn't described a textual language, this is probably not true

3b) Indexes like this can be largely generated automatically from topic titles - there's no need to load the help author down with creating a manual one.

4) One can see a few areas where CHM could be improved on judiciously, like making it easier to combine help files, and improving the relevance of searches - although it's not bad to start with.

Leave a Comment

(required) 
required 
(required) 

  
Enter Code Here: Required
 
Page view tracker