The Story of Help in Visual Studio 2010

Today I’ll be discussing the Help Viewer in Visual Studio 2010 – where it’s been and where it’s going.

This post is the first installment in a three-part series. 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 sneak preview of changes coming to the help experience in Visual Studio 2010 Service Pack 1 (SP1).

Part 1 – Why A New Help System?

In August 2007, April Reagan, a Program Manager on the Visual Studio content authoring team, submitted a paper titled “The Case for Significantly Improving Developer Help” for Bill Gates’ semi-annual ThinkWeek. At the time, Visual Studio shipped with Document Explorer (dexplore.exe) which utilized the proprietary Microsoft Help 2 (.hxs) format. The paper described the following issues with the help experience in Visual Studio:

  1. Not being able to find the information you need is a common problem. F1 Help and Search do not work as well as they should.
  2. The performance of the help system – primarily start-up, topic-load, local search results – is one of the biggest problems.
  3. The offline MSDN library install is fragile due to the complexities of the help system.
  4. The proprietary nature of our help format offers little incentive for partners to develop authoring tools and cannot be easily adopted by developers in their own products.
  5. On the content production side, the help platform saddles us with outdated tools and processes.
  6. Finally, and most importantly, no single team at Microsoft owns solving these problems.

The paper was well-received and, in early 2008, a team of fewer than a dozen people was funded to replace the Help 2 system. Internally, the project was referred to by the codename “Help3.”

The Help3 team was asked to solve an additional problem. Long lead times for content localization require that documentation be ship-ready well in advance of the product release. Because of this business requirement, some of the in-product documentation can be stale or incomplete at RTM. In addition, developer documentation for all of the Microsoft platforms is produced and updated frequently. Developers needed a way to quickly and easily download documentation updates after RTM. The current help system had no mechanism for providing on-demand updates from the Web.

In April 2008, Visual Studio architect Rico Mariani wrote an internal white paper that outlined a vision for the new help system. Rico’s fundamental theme was “replacing custom help-specific technologies and experiences with standard ones – embracing existing standards for deployment, display, and operation.” Instead of fixing bugs in the current help system the Help3 team began implementing a simpler, more open solution.

Among the first things the team needed to do was to settle on a content format that could be generally released. The Help 2 .HxS format was encumbered by intellectual property and required significant interpretation/analysis at deployment time. The operating system did not provide a good alternative. Microsoft Windows® supported three separate help systems: WinHelp (.hlp) – an RTF-based format that was deprecated in Windows Vista, HTML Help (.chm) – a compiled HTML format that did not support our target scenarios, and Assistance Platform Help (.h1s) – another proprietary solution that would not be made generally available.

The team settled on a format in which XHTML content is stored in a ZIP file. Not only did this provide a simple, standards-based foundation for the new help system but it was highly compatible with the content format used in the online MSDN Library.

But what approach would be used to enable updates from the cloud? After some debate, the team chose the Microsoft and TechNet Publishing System (MTPS) – the web platform for the MSDN Library – to distribute topics for download. The MTPS team, guided by Kimberly Wolk, had been working on a content distribution solution that could be leveraged quickly. This decision enabled a model in which our content authoring teams could target online distribution as their primary publishing channel for technical documentation. Local help would be a cached subset of whatever was available online.

Building a new help system from the ground up proved a formidable challenge for a small team that had gotten a late start. In November of 2008, the Help3 team was consolidated with the online Library team to form the Library EXperience (LEX) team. For the first time, responsibility for delivering the overall online and offline Visual Studio help experience was now centralized in a single team.

The new team embraced Rico’s guidance of moving to standard experiences. In March of 2009, just prior to the Beta 1 release of Visual Studio 2010, the team scrapped a local help application under development in favor of a browser-based local help viewer. Developers would be able to consume help in their browser-of-choice while using their favorite plug-ins both online and offline. While LEX was well aware of existing browser limitations, the team believed that the long-term benefits of this approach would outweigh short-term issues. (We’ll come back to this subject in more detail in Part 3.)

Two other important deliverables rounded out the solution. We delivered a public client-side API to give third party developers full access to local help content. Our goal was to enable content re-use, mash-ups and alternative help experiences. (Information on this API and the underlying content format is available in the Help Viewer 1.0 SDK.) In addition, the LEX team built a back-end system for packaging up downloadable content. The back-end packaging system proved to be challenging because of the size of our documentation and the frequency with which writers updated their content.

The net result of all this change was that the Microsoft Help Viewer would not ship in Beta 1. Developers would see the new help system for the first time in the Visual Studio 2010 Beta 2 release, leaving little time in the schedule to incorporate additional customer feature requests prior to the RTM release. Consequently, the first service pack would be a very important release for the new help system.

Next: Overview of Help Viewer 1.0

Installments in this series:

1 – Why A New Help System?
2 – Overview of Help Viewer 1.0
3 – Help Viewer Improvements in SP1

This entry was posted in Microsoft Help Viewer, Visual Studio 2010. Bookmark the permalink. Both comments and trackbacks are currently closed.

10 Comments

  1. Herbert
    Posted November 4, 2010 at 2:12 pm | Permalink

    Thank you all very much for cleaning up the mess of help files. Let me add a few comments/questions:
    0) What does this mean to my own developments? Does it help me to get my product out the door quicker and without a 3rd party help tool?
    1) How does sandcastle fit into this? e.g. for my own VS add-ins.
    2) Will your tools become available to build help from .doc, .pdf and .xml files?
    3) I teach students .NET since 2003. Over the years, the missing help tools and standards have not been the problem. What has become unusable are the complicated intellisense informations added since .NET 3.5 (Lambda, special delegates, …). If you are not writing code on a daily basis, a “fly-by-night programmer”,a teacher, or a student, then intellisense like the one showed for
    Parallel.ForEach()
    is not useful at all.
    Why are those programmers so important to MSFT? Well, they have terrific specific domain-knowledge. From hobbies like digital railway models to cableTV billing systems. These people will write and sell the next gen apps for Windows Phone 7 and other upcoming consumer products. No Redmond based team can beat them in terms of domain knowledge.

    So very often I wished I had an “explanation for intellisense”, a wizard helping me building Lambdas and the like:
    The best help still is to avoid calling the Help system.

    And: code snippets available in VS are not used or mentioned in the help texts at all.

    So please integrate help, intellisense, code snippets …

  2. Posted November 12, 2010 at 4:06 am | Permalink

    Please implement Dynamic Help for vs2010!!!

    i really miss it!!

    Bring back the Dynamic Help in Visual Studio 2010

  3. Sergei
    Posted January 10, 2011 at 3:32 am | Permalink

    “So please integrate help, intellisense, code snippets …”

    I purchased MS Dev Studio 2010. (This is the first attempt in my life.)
    Intellisense doesn’t work!
    Compiler error counter doesn’t show! (I have to seek for it)

    Give me back my money!

  4. Michael Kingsford Gr
    Posted January 10, 2011 at 5:22 am | Permalink

    The new “help” system in VS2010 sucks so bad that I now resort to google for my help enquiries ALL OF THE TIME.
    If one (for instance) wishes to investigate what the “if” statement syntax is in VB.NET, then pressing F1 is of zero use at all.
    What it presents is a general search of all Microsoft MSDN, Not targetted to Visual Basic.
    Not targeted to the “If” statement, not targeted to .NET 4.
    Not targeted at ALL!!!
    You complete and utter bastards.
    Bring back the help of VS2005. At least it worked.
    The current ‘help’ system is a total HINDRANCE.

  5. Posted January 10, 2011 at 12:33 pm | Permalink

    I agree with the other comments about the help system here, the new help system in VS 2010 is terrible. F1 doesn’t work like it used to (and this was the primary way I used the help system previously) with regards to context, and the search system either doesn’t find anything, finds too much, or usually finds a lot of stuff that isn’t actually what you want.

    Also, I hate the browser and I don’t see it as having any benefit for a help system. Yes the old systems were slow to start (a big, annoying problem), and yes they had other issues too, but they were actually better than what we have now with VS2010.

  6. Posted January 10, 2011 at 12:35 pm | Permalink

    … forgot to say in my last comment, I too almost always use Google over the help system since upgrading to VS2010. It’s generally easier to find what I want, and since it also runs in a browser the VS2010 help system doesn’t really provide any benefits.

    In the odd case where I’m using VS2008 (because you guys also removed compact framework/CE development support from VS2010 which is mission critical to some of our business application) I do use the help system, but of course, that’s the old one.

  7. Bionic
    Posted January 10, 2011 at 4:54 pm | Permalink

    I love the new system. But perhaps it’s because I’ve been using C# lately… I think if I were doing C++ I’d be better off with 2008.

  8. tom
    Posted January 12, 2011 at 11:48 pm | Permalink

    I still remember the VB 6 help system which was efficint, quick and complete.
    give me that experience with c# and .net!

  9. Mark
    Posted January 28, 2011 at 5:44 pm | Permalink

    I suggest firing the VS2010 help team, and any of those responsible for turning the VS2010 help(less) system into what it is today. Without fail, it seems like you make massive changes to products based on the input of a few select individuals, many of whom have less experience or exposure to the product than daily users.

    Let your users drive your changes, not your private group meetings.

    • BV
      Posted April 7, 2011 at 9:21 pm | Permalink

      Mark’s suggestion is excellent! just fire the whole VS2010 help team that botched the whole help system. I just installed vs2010 sp1, which comes with the latest help viewer 1.1 that has the TOC treeview, which is better than nothing, but is far inferior to the old and trusted document viewer. How could someone spend years to transform the good (maybe a bit slow, though) help system into a joke like this?

      This is by far the worst ever product from MS.

      like many of the folks commenting here, i either use vs2008′s help (and run the risk of reading outdated content) or google for whatever i need.

7 Trackbacks

%d bloggers like this: