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.