The Story of Help in Visual Studio 2010 (Part 3)

This is the final installment in a three-part series about the Visual Studio 2010 help system. Part 1 offers a behind-the-scenes look at the evolution of our new help system. Part 2 is an overview of the help experience delivered with Visual Studio 2010. Part 3 offers a preview of changes coming to the help experience in Visual Studio 2010 Service Pack 1 (SP1).

Part 3 – Help Viewer Improvements in SP1

Since the release of Help Viewer 1.0, we’ve been talking to developers, listening to your feedback and observing the use of Visual Studio help in our usability labs. I’m now going to give you a sneak preview of the next set of improvements we’re planning for the Visual Studio 2010 help experience.

As I described in Part 2 of this series, the LEX team has made significant progress towards addressing issues in previous versions of the Visual Studio help system. However, our decision to use the browser to provide offline help received some strong feedback, particularly from developers who had built up a lot of muscle memory with Document Explorer (dexplore.exe). The central theme of this criticism was that they found themselves less productive using the offline viewer in Visual Studio 2010. In response to this feedback we’ve made a number of changes to the help experience which will be delivered in Visual Studio 2010 Service Pack 1 (SP1).

New Features in Visual Studio SP1

We’ve made three major changes to the Help Viewer in SP1. First, we’ve abandoned the browser-as-local-help-viewer and implemented a simple client application for offline help. The help window is no longer lost in the set of browser tabs you have open and the help application icon can be easily located in the taskbar. F1 Help re-uses the currently active tab instead of creating a parade of open tabs that must be manually managed. The help application can be sized and placed anywhere on your desktop and retains its size and placement across sessions. The navigation panel width is resizable and it can be placed to the right or the left of the content.

Second, with the flexibility we gain from building a client application, we’ve re-introduced many of the productivity/efficiency features found in Document Explorer. The viewer features four navigation tabs: a fully-expandable table of contents that can be explored without reloading the current topic, a keyword index, a Favorites and History tab, and a search results pane. The search results pane allows you to refine your search queries without losing your current topic context. In addition, context menus and shortcut keys allow you to access features quickly without excessive need for a mouse.

Finally, without the security restrictions of the browser, we’ve improved the ease with which you can manage local content. A direct link to the Help Library Manager is built into the viewer window. We provide improved guidance if you’ve never downloaded local documentation or if you press F1 on a topic for which local help is not installed.

Paul O’Rear, a Program Manager from the LEX team, has created a visual walkthrough of the new features in our SP1 Help Viewer. This is an early build but I want you to give you a look at what we’re working on:

While we were constrained in the amount of change we could introduce in a service pack, we believe these improvements will address many of the issues our power developers had with the RTM viewer.

For users who prefer to consume online help, the help experience will continue to display in your default browser. The largest benefit over just consuming the online MSDN Library via your search engine of choice is that we enable F1 Help.

Why did we make these changes?

We made these changes because you asked for them. In addition, we’ve adjusted our philosophy towards the help experience. In Visual Studio 2010, we focused on keeping things simple and standard and embracing the Web. Moving forward:

For online help, we fully embrace web technologies while providing in-product contextual help and continuing to invest in great experiences for the broad base of developers.

For offline help, we provide an efficient experience that leverages the capabilities of Windows for developers who have sophisticated productivity needs.

When will the new local Help Viewer be available?

Our plan is to deliver the new Help Viewer as part of Visual Studio Service Pack 1 (SP1). I’m not able to talk about SP1 dates at this time but I expect to provide more details in the not too distant future.

How do I provide feedback on the new viewer?

There are three main ways to provide your impressions of this new viewer:

Moving the help system forward has turned out to be quite an adventure. We’ve made some mistakes along the way but I think we’ve also gotten a lot of things right. We’ve set twin goals of both addressing the issues with the previous systems and enabling new online and re-use scenarios for our broader community. As always, we appreciate your feedback on how we’re doing.

Can we view help content in tab of Visual Studio IDE?
Can we use new “document explorer” to view help in online-only scenario?
Both options were possible in 2008 and I miss them.
Is it possible to choose which web browser is launched for F1 or system-default browser is used? My default browser is FireFox. For Visual Studio F1 help I’d prefer to see it in VS studio tab or dedicated “document explorer” (even in online-only mode). If this is not possible I’d like at least to chose different browser for F1 (say Chrome) so VS help does not mess with other thinks.

The local Help Viewer in SP1 is a standalone app and won’t display in a tab of the Visual Studio IDE. The best option for people who want in-IDE help is to install the MSDNKeywordIndex add-in (also available from the Visual Studio Extension Manager). The add-in works in local mode and supports F1 so it will keep help from displaying in your default browser. Online help in SP1 will continue to display in your default browser and that is not configurable.

You made the changes because we asked for it. That begs the question: Who asked for status quo?

Joke aside, did you do something about the slow startup of the help system? That’s the main reason I deactivated F1. I use F2 a lot, and whenever I missed and hit F1 by accident, I could observe my flow vanish.

The slowness isn’t the problem, really, but that Visual Studio is locked while the help system is starting up. Not a problem when you want the help, a much bigger problem when it starts accidentally.

Yes, we fixed this issue in Visual Studio 2010! We hope that between eliminating the startup penalty and other improvements to F1 that developers will regain the benefits of F1 Help. I discuss this and other improvements to the help system in The Story of Help in Visual Studio (Part 2).

I am glad you ae giving us back a lot of the features from Dexplore that were missing in Help Viewer.
One thing that I am still not seeing is ‘Help Collections’. A lot of our users (we develop our own DotNet language) have asked for that. They would like to see an index or search results for a particular subset of the documentation (like our product documentation).

1) It wasn’t shown, but I presume the spilt between the navigation and content is adjustable?

2) When trying to disambiguate overloaded contructors from the TOC for instance, there needs to be a tooltip if the naviagtion area is narrow so you can see the full text as you hover over each entry.

3) For a new tab, the standard way would be middle or wheel click not just right click and ‘open in new tab’.

4) I see you have text size control, but hopefully the content is viewed using a browser control so ctrl+wheel will work as zoom just like in a regular browser (IE9 browser control will do this very nicely with its DirectWrite rendering 🙂 (and if that can be made to work on the navigation pane too, that would be really nice (and so easy if you’ve built this using WPF)).

5) Middle click on links in the content should open a new tab too, just like when viewing in any browser.

6) Choice of font for use in the navigation pane would be nice, I much prefer something like Verdana when there is a lot of text to focus on and I have a notebook with a 13″ full hd screen so these things are important, more so than on a big desktop monitor!

I’m very happy that you address the local help, which sadly I have stopped using, because it has the potential to be a superior experience over web search. However, the demo doesn’t bode well for how local search will perform.
First off, there doesn’t seem to be a topic filter. This is cruical and something that a plain web search doesn’t provide.
Second, the result ranking is completely off. Look at the first results for “BinaryReader”: Properties and Constructor. Now compare that to a Bing search, that returns an overview as the first result (with links to related topics), then turorials etc. Very nice. It would be great if the local search incorporated relevance rankings from e.g. Bing (it’s your search engine) and did smarter things with the meta data that you have for all the help topics. Then local help could become a viable option again.
But this is a step in the right direction!

Are there any improvements to updating offline help. The main thing is more granular options. For example I installed most of the offline help. I then just wanted to update the ALM/ content, but this appeared to be impossible. I had to download all the packages and on a slow line that is a big problem

This looks pretty good. It looks miles ahead of the current viewer, in any case. One thing I still miss in the demo though is the content filter. It’s hugely important to be able to filter away irrelevant content, such as C++ functions when doing C# development.

The other thing I missed was a proper demonstration of the search functionality. Searching for BinaryReader is setting the bar pretty low. Show a video with a search for some difficult but common thing like “String” and then we can start to have more confidence in the improvements.

“Filtering did not make it in for SP1. It is on our list of candidate features for a future release.”

There were two types of filtering in 2008 and prior. One was the TOC/Index filter, and one was the filter for example code/prototypes in the main reading panel. Are both missing for SP1, or just the TOC/Index?

Really, both are essential to make a useful help system. Waiting for SP1 is bad enough. Waiting for SP2 or 2012(?) for features we had (for 15 years or so) would be more than a bit much.

In the embedded video, at time 3:19, where Paul is demonstrating the Index feature, he says “It will automatically go to the *first* topic in the list”. However, when he hit enter it went to the *eighth* topic in the list.

BTW, the titles of the native topics need cleanup. Again referring to 3:19, the first title is: “Bitmaps, Device Contexts, and Drawing Surfaces (Windows) – .Net 3.0”. It should not have “.Net 3.0” in the title as it has nothing to do with .Net.

The apparent behavior issue at 3:19 is due to post-production video editing and not due to a product issue. Nice catch, though! The “.Net 3.0” string in the title was an issue in that build and has since been fixed.

It’s quite dissapointing to still hear that Microsoft isn’t agile in their software development processes within Visual Studio and from what it sounds like you have no intentions of doing so in the next release of the product.[You posted about going to Azure…but if the plans are anything like Windows Live Essentials’ 18 month release cadence god help us]

Sure the feature teams are agile and probably doing scrum and releasing code every month into some mainline somewhere, but honestly to hear in this day and age that “You are right that by the time we ship Beta 2 in a product cycle, it’s too late to make significant feature changes.” it just reaffirms that the developer division doesn’t get the new world and the developer division will have to be dragged kicking and screaming into the cloud.

Look for a moment at how Sales Force does it’s release process and how developers get new reliable tools on a really frequent clip. Look at infragistics….Look at Telerick…the list goes on and on.

It’s even more dissapointing to hear that “{VS 2010 service pack {1} is much smaller than VS 2008 SP1”.

VS 2008 SP1 wasn’t anywhere near the scale of say a Windows XP SP2 service pack…sure there were features…but dissapointingly few valuable ones(I’m looking at you Mobile Developer tools/ASP.NET/C++).

I’m not saying that Service Packs are the vehicle you should be using to release new features (service packs are fixes thanks very much)…but in conjuction with SP1 there should be a FP1 released….kind of like the Windows Plus packages of yester year…and have FP1 and SP1 ship simulateously.

And to hear you state that the disorderly release process you have now with hotfixes, “alpha” power tools, and VS add-ins is somehow a viable solution is quite disengious.

You have a mess on your hands with VS….and until you can rapidly release say quaterly updates (with features) for VS on say, shockingly, a subscription plan, like the one you ARLEADY have….then I fear my development platform is slowly but surely moving to other tools(eclipse and GIT are getting “good enough), other runtimes (I’m looking at you HTML5), and other platforms (IPhone especially).

Back on topic with the help system….you guys choose wrong…way wrong and it’s good to see something changing….but I fear this will be far too little far too late…but I guess we’ll see.

Microsoft still don’t seem to innovate here, clearly the help system experience have degraded to the point that searching in google or bing for the keyword followed by “msdn” became the best way to get help.

Your toy help viewer is going in the good direction but it’s still not providing innovation relative to the competition, not even catching up with it, worse it’s not even as good as the help system in previous Visual Studio versions…

I get it that microsoft don’t want to put resources without any good competition on .Net have no insensitive to do so, but it’s pretty sad.

Look at the line “BinaryReader.Close Method (System.IO)” an split it up :
* “BinaryReader” : Useless it’s alreay written 2 lines above that we are in that class
* “Close” : Usefull info, the name of the method
* “Method” : Useless it’s already said 1 line above that we are browsing methods
* “System.IO” : Useless displayed 3 lines above it.

Basically the whole tree display names that should be reserved for search (And even in search the emphasis of the namespace should be less than the one of the name, for example in grey text, except if the namespace is a matching term).

The online version is a little better as only “Method” is repeated (And they repeat the class name on the “Methods” node, while it’s on the line above already and the tree view already convey this fact)

Looks fantastic – thank you! A modern dedicated UI with the clean design and content that comes with VS 2010.

Will the “help web server” still be required? I found it somewhat frustrating as a laptop user who codes on battery power. Each time it opened it popped up a somewhat annoying balloon tooltip and I had to explicitly close it to conserve my battery power. If it’s possible, it would be fantastic to see the help server integrated in the viewer process or completely hidden from the end user.

Favorites never worked well in the old document explorer – the new experience looks great. Thank you!

The Help Library Agent performs two main functions in the product today. First, it serves help content to your browser when you’re working in Local (offline) mode. Second, it supports F1 Help for Visual Studio partner products when you’re in Online mode. Because partner products can’t publish help to our online MSDN Library, we re-route the F1 query to dispay help from your local content store. The new Local viewer we’re introducing in SP1 will enable us to eliminate the Help Library Agent but we need more time to put a better online help story in place for and with our integrating partners. So the Agent will still be required in SP1. Note that, in recent versions of Windows, you can hide the taskbar notification from: Control Panel\All Control Panel Items\Notification Area Icons.

Shouldn’t the help favorites be integrated with Internet explorer favorites which being able to choose the folder name and location we wanna place them under? This way when moving machines and installations around we would never loose our links, the way it’s dine right now who knows where we are going to need to dig the links out of in order to keep them as useful links for the future. If we loose the resilience and stickiness of our favorites links, it defeats the purpose of having favorites… Since they wont last more than a year.

I was excited to hear of an help overhaul, and expected some real innovative stuff, such as reading my code and offering good help suggestions based on what I’m _trying_ to do as opposed to basic keyword search, solution scenarios combined with documentation and links to question answer posts relating to the problem I’m facing, if I am facing a problem, would all have been a great innovation.

But it seems typical Microsoft to not be pushing higher complexity innovations at all these days, I really wish bill gates was still around, I think ballmer has no vision and it’s holding the company behind in.many respects.

I like the current browser-based help system because it is easy to have many topics open in multiple windows & tabs. I don’t have to take screenshots to be able to see more than one topic at at time. 😉 Silverlight crashed so I haven’t seen the beta vid yet but I hope it’s possible to have multiple windows & tabs of help.

I think the tabs in the navigation pane should be at the top. In a large screen environment all of the controls in the simple viewer are at the top. You should prevent the amount of mouse movement that is needed to change tabs.

Sorry, but the offline help stinks- way, way too slow, unusuable. The online help is frequently slower and harder to search then just going to google.

I’m not sure how others use it, but I normally want to know more about a particular method and it used to be about 3 keystrokes and then I enter the method name into the old help- and was pretty quick. The new help is not.

Also- I’m working in silverlight all day, would it really be all that hard to get it to STAY on the silverlight setting when I move to another obj or method, etc?

Having to login first is also a major wtf- it shouldn’t care who I am just to look at the help.

The thing that I want help with in Visual Studio is finding an option that I know I’ve found before. The current menu item to model window system makes it impossible to find something. I wish there was a search/help box that indexed just menu items, and the things they open. That way I don’t have to manually hunt through every button and tab in every menu item to find the thing I’m looking for. How was I supposed to find an option under Tools -> Options -> Advanced Options -> Advanced -> Settings -> etc. I usually know that I want an option that had a label that used the word or phrase that I can remember. So if help could open that up, instead of me digging around, it would be wonderful. A system a lot like Win 7 control panel search.

Whoever thought of Help Viewer 1.0, what were they thinking? That feature was more cumbersome and counter-intuitive than it was worth. I just felt lost and frustrated trying to find the help on a particular issue.

Truthfully, I ended up having to google almost everytime I needed to help on a particular topic.

I just loved being able to install the latest Visual Studio Version, and topping it off with the installation of MSDN files. In that way, I had all help files at the click of a mouse.

The former Help system had great features:

I could filter, based upon the current programming language.
I could use the table of contents, the index, or even search by keyword.

It was all information conveniently categorized, located, and accessible without maneuvering through a lot of circuitous actions

Hmm, mixed feelings here. On one hand, the browser-based help in VS2k10 sucks. On the other hand, I feel like browsing the help system *does* belong in the browser. I’ve already got a browser, it is very good at showing documents, and even better at showing *lots* of documents (using the magic of tabs).

I don’t particularly want to have to rely on a separate “simple client application”, not if I could use the extremely advanced and powerful client application called a “browser”, which I already had open.

It is a bit sad to see the team give up on this experiment, and just go “hey, we’ll just make *another* crappy client app that doesn’t support 5% of the features that the user’s “main” document viewer (the browser) supports, and which will lag further behind because browsers improve, and our help viewer doesn’t, at least not at anywhere near the same pace”.

Cynical, perhaps, hardly inaccurate. I’d love to see improvements to the browser-based help, rather than Yet Another Application To Do the same thing as all the other applications.

A new viewer is definitely welcome, but is there any news about tools to actually generate the help? I hear a lot of griping from people that have to deal with Sandcastle and its status isn’t exactly what I’d call “supported”. It’d be nice to know that those of us who need to generate documentation can actually get it inside your shiny new help viewer. To me that was the real benefit of previous help technologies: I had tools to author HTML help and WinHelp. The last time I looked at Sandcastle it involved using some third-party tool to maintain sanity, possibly bound together with duct tape and chewing gum.

Hello Owen, are you specifically asking regarding a Microsoft Toolkit for producing documentation?

With WinHelp and HTML Help, there were proprietary compilers required to produce the Help format. Additionally, there were tons of 3rd party tools that supported more sophisticated authoring experiences.

With Help Viewer 1.0, our new format is simply .zip based and renamed to .mshc. This of course does not require a Microsoft specific solution to support that.

If I understand your request, it’s really for a supported Sandcastle like toolkit that is specifically aimed around generating developer documentation and doing reflection on .NET assemblies. This is quite a different kind of ask than the toolkits that were provided for WinHelp and HTML Help.

To that end, we’ve worked hard to ensure that Sandcastle continues to support our new Help format, but have also worked closely with several 3rd party Help Authoring Tool vendors to enable them to provide a rich Help authoring experience that supports our new format.

You can find info about a number of these Help Authoring Tools (HATs) on my “The Help Guy” blog here.

Thanks for listening to developers wrt to 2010 help.
Effective help is AS IMPORTANT as the IDE and the frameworks.

My vote to Add:

1. Simple XML comment documentation generation into native help viewer format.
We have been able to 1-click generate JavaDoc for Java for the last 15 years.
Why is this something I have to buy or assemble and configure myself for VS.
XML comments – great idea – lousy implemetation and support since it was first introduced.

2. User-defined multi-level folders in Help Favorites for organizing help links. (ie IE).

4. Better Print Support.
** Sometimes I want to to be able to sit in the sun with a Pen and Highlighter
— Print Preview including # of pages.
— Consistency of printed formatted output: fonts, borders, …

5. Local Help delivered in assemblies rather than 1 gigantic blob.
— I can plug-in/out assemblies (SQL, Win32, Web …) as desired.
— Local help assembly cache mgmt includes locally developed assemblies (See 1).

What about bookmarks? won’t it support bookmarks? It’s really frustrating to open all those links again after restarting Windows to apply those downloaded updates. Please add support for bookmarks too. And switch to WPF has made VS so slow, just like Vista. Please fix it

Thanks for this. Index, TOC, & sync w/ TOC are what I was missing from the VS 2008 help viewer. Search results look pretty good too. Filtering might be nice, but is mostly frosting from my view, as long as search works well.

Any word on VS Express?
How about sharing on intra-net? There is a mention of con-current write – But, can’t we simply create some kind of lock-file? To install these mostly read-only content on every PC just kind of waste.

SP1 Beta installs on all editions of Visual Studio 2010 (Express, Professional, Premium, Ultimate). We’ve worked to minimize the “waste” you describe by enabling developers to download only content that is relevant to them. But it’s important this content is local for performance/productivity reasons. For users who don’t want to use the local help viewer, we continue to support an online experience that gives you access to the complete MSDN Online Library.

Thank you very much on moving to an html website standard style.
and i hope you consider the following:

1. It would be nice if you give the developer the option to use ur new (client application) or use the internet browser,
especially that the new browsers are much faster and implement GPU processing.
2. the placement of ur new client app or the browser is remembered for the help system and across several monitors as developers are more and more having multiple monitors.

SP1 sounds like a good development – moving things out of the browser (esp. when working on a laptop disconnected from the Internet – and the browser throwing warnings about being in Offline mode).

However, the biggest pain for me is how every time Help is launched, it defaults to showing code samples in VB. I prefer C#, yet every time I change the tab, the setting isn’t remembered the next time I load the help. Granted, the tabs are better than the older checkboxes in a dropdown menu, but it’s still a hassle to have to set preferences every time when they could easily be persisted.

As we discussed offline, your code example language preference is stored in a cookie. If you have cookies disabled or you only allow them for the duration of the browser session, you’ll need to add exceptions in order for the example code block control to work properly. For the local viewer (RTM version) you’ll need to allow cookies from 127.0.0.1. For the online Library, you’ll need to allow cookies from microsoft.com. We serve the cookie from microsoft.com to ensure your preference works across both MSDN (msdn.microsoft.com) and TechNet (technet.microsoft.com).

I haven’t tried the viewer 1.1, but I definitely feel that a client app is needed like dexpler. The online stuff doesn’t serve good especially when you are trying to go through quickly from one topic to another (when learning new features) – table of content (in treeview and not as links) is a must.

I am glad the UTTERLY HORRIBLE Help in VS2010 will be replaced. Nothing can be worse than that. The price for VS2010 Ultimate has gone up €2000 this year (!), the Help system has gone back 10 years. Scandalous. Normally I am capable of contributing in a positive way. You are making that very, very difficult for me.

So, my wish for the next Help Viewer: get rid of all that whitespace! Why oh why is there such an abundance of whitespace? Who asked for two lines of whitespace for every line of text? I cannot imagine we did. Sometimes there are online 15 lines of text on a complete screen. In what way can that be good? So get rid of it or, at least, let us have our own stylesheets for each window. You will not be able to create something that satisfies every user.

While I’m certainly not a fan of the Help system for the last ten years, I have to take issue with all of you saying that Microsoft’s Help isn’t up to the level of the competition. If you want to see some REALLY bad Help, try Google. Or IBM/Lotus. Or Novell. None of these can even come close to what Microsoft’s Help can do.

This is definitely an improvement, I was really missing the keyword index…

However, there was another very useful feature in earlier versions of offline help, which has disappeared in VS2010 help : the member filter. It used to be possible to hide inherited members, and I used that feature all the time… Now I have to examine the members one by one to see if they’re inherited or declared in the class I’m looking at. WPF controls have more than 300 members, so it’s almost impossible to see which members have been declared by a specific control without viewing the class in the Object Browser or in Reflector

Help should be integrated into the development environment, like it used to be in VS 2005. That’s why they call it Integrated Development Environment. Having to switch to an external viewer is not productive. I don’t like the new help viewer idea.

[…] Help Viewer – The new local Help Viewer is a simple client application that re-introduces key productivity features including a fully-expandable table of contents and a keyword index. For additional information about these improvements, check out Jeff Braaten’s post here. […]

[…] Help Viewer - The new local Help Viewer is a simple client application that re-introduces key productivity features including a fully-expandable table of contents and a keyword index. For additional information about these improvements, check out Jeff Braaten’s post here. […]

[…] Help Viewer – The new local Help Viewer is a simple client application that re-introduces key productivity features including a fully-expandable table of contents and a keyword index. For additional information about these improvements, check out Jeff Braaten’s post here. […]

[…] Help Viewer – The new local Help Viewer is a simple client application that re-introduces key productivity features including a fully-expandable table of contents and a keyword index. For additional information about these improvements, check out Jeff Braaten’s post here. […]