• Download Visual Studio 11 Beta (general availability)
• Download Visual Studio 11 Beta (MSDN Subscribers)

The Help Viewer team’s been busy since I blogged about new features in the Developer Preview. In this post, I’ll cover new features we’ve added in the Beta release:

• TOC Filter
• Keyword Index: “Begins With” vs. “Contains”
• Docking Windows
• Color Themes
• Search Filter UI
• Improved Performance

Setup and Configuration

If you’re performing a clean install of Visual Studio Professional, Premium or Ultimate, you’ll be offered the chance to download local Help content at Visual Studio first run or when you first set your Help Preference to “Use Local Help.”

Installing content during first run is a convenience, not a necessity. You can download and install local Help content from within the Help Viewer at any time.

Online Help is the Visual Studio default as it was in Visual Studio 2010. If you’re doing a clean install of Visual Studio and you want to use the Help Viewer, you’ll need to set your Help Preference to “Use Local Help” From the Visual Studio Help menu.

Table of Contents (TOC) Filter

The TOC Filter displays all topics with titles that contain an input filter string. But instead of displaying the results in a flat list, topics are presented in a sparse tree with their relative relationships intact. This view of the TOC can help you discover topics that are distributed across the TOC and clusters of content that represent in-depth treatment. The filtered view of the TOC can also help developers better understand how our reference content is organized.

For example, if I filter on ‘system.xml’, I can see topics in the .NET framework documentation where I expect to see them. But there’s a cluster of documentation in the Visual Studio debugging content that discusses troubleshooting exceptions. It would have been time-consuming to build this mental model of related content through Search queries alone.

To keep the list compact and manageable, we collapse empty TOC levels with an ellipsis (…). Placing your cursor over an ellipsis reveals the path to a topic or topic group.

If it takes a long time to construct the filter view (as it does in the above example), we display a banner message: “This filter may take a long time. You can change the filter or use search instead.” You can cancel the filter, switch to the search pane or just wait for the filter action to complete.

Keyword Index: “Begins With” vs. “Contains”

The keyword index now functions in either of two modes: “Begins With” or “Contains.” In “Begins With” mode, the keyword index displays items that begin with a given input string. This is the traditional behavior of the index control. When the keyword index is in “Contains” mode, it depicts items that contain the input string. To toggle between modes, click on the filter icon or press Ctrl + K.

Let’s look at how the same ‘sql’ filter string offers a different result list in these two modes:

Begins With	Contains

Docking Windows

Docking windows were present in the earlier Developer Preview but they were still a work-in-progress. By supporting this capability, Help Viewer provides greater consistency with the Visual Studio IDE and it addresses a set of scenarios that might otherwise have required additional Viewer Options. (If you’re unfamiliar with Visual Studio docking windows, you may want to learn How To: Arrange and Dock Windows.)

While the possible configurations are nearly endless, some scenarios in which this feature can be helpful:

Example 1: Navigation panel docked on the right side of the content pane. This common configuration was a Viewer Option in Help Viewer 1.1.

Example 2: Navigation panel docked above the content pane. This configuration minimizes horizontal real estate which can be helpful when developing on a single display, for example, a laptop.

Example 3: Search pane docked in content window. This configuration is nice if you want to have more area to display search results.

You can also display topics side-by-side or drag topics outside of the main Help Viewer window. As you’d expect, your docking customizations persist across Help Viewer sessions.

Finally, if you want to restore the Help Viewer to “factory settings,” open the Viewer Options dialog (Ctrl + O) and “Reset Window Layout” by selecting the ‘Reset’ button.

Color Themes

Visual Studio 11 Beta introduces a new visual design and user interface. As a companion app to the IDE, Help Viewer 2.0 Beta provides the same visual design and color themes.

You select your Visual Studio color theme in the Options window of the IDE.

The next time you launch the Help Viewer, it will honor your Visual Studio color theme. Currently there are two theme options: Light and Dark.

Help Viewer Light Theme	Help Viewer Dark Theme

NOTE: We’re currently receiving a flood of strong feedback on the user interface changes and it’s likely we’ll make revisions in response to that feedback. Whatever changes are made in the IDE will be reflected in the Help Viewer. If you’d like to weigh in on the new user interface, the best place to be heard is on our Visual Studio UserVoice site or on Visual Studio Connect.

Search Filter UI

We now have UI support for the search filters I described in my post on the Developer Preview. When entering a string into the search box, you’ll see a list of your last three searches followed by filter options. The filter options enable you to discover the available filters and add them to your search query. For example, clicking on ‘title:’ automatically appends it to the search string.

Improved Performance

Performance is a key focus of Visual Studio 11 and that extends to the Help Viewer. Help Viewer 2.0 is faster than Help Viewer 1.1 in all of our performance benchmark tests.

Our biggest gains come in moving from an HTTP API to a COM API (with a managed wrapper for .NET programmers).  We no longer pay the HTTP network cost before retrieving data. (And you no longer have the Help Library Agent sitting in your taskbar.) Because the Help API is a core component of Windows 8, we had encouragement from our friends in the Windows team to optimize both our performance and memory footprint.

Other improvements include:

• F1 Help – We revised viewer code to reduce UI blocking tasks and to optimize for fast startup by delay- or background-loading of nonessential data with the goal of delivering as fast an F1 response as possible. If you haven’t tried F1 help in a while, I encourage you to give it a look.
• Search Index – Index functions have been parallelized using the .NET Parallel Constructs which speed index functions on multi-core machines. We’ve made a number of non-specific tweaks to fine tune performance including denormalizing data to reduce the number of index lookups per query. Finally, several caches are created at index creation time to improve search times.
• Rendering – The content rendering system has been rebuilt from the ground up to be more extensible, flexible, and secure. By moving the rendering and branding into C# code (reducing the need for JavaScript and complex XSLT transforms) we have significantly reduced rendering time.
• Table of Contents (TOC) – We modified the TOC API code to reduce the number of calls necessary to determine if a TOC topic has children or not. We also cache the results of TOC filter operation to increase the speed of repeatedly used filters. Note that the filter cache is reset on any ‘Manage Content’ operation.
• Content Download – We optimized our use of BITS to improved content download times. In addition, content merge time have been reduced by over 50%.

…and much, much more

We’ve made numerous fit and finish improvements throughout the Help Viewer, for example, in the area of keyboard support. I’ve already blogged about some of the other significant improvements so if you’re interested in the following features, please read my earlier post on new features in the Developer Preview:

• Simpler setup and configuration
• Integrated content management
• Search filters
• New help runtime (no more Help Library Agent!)

Finally, we’ve added improved support for content management in enterprise and behind-the-firewall scenarios. I’ll save the details of those features for a future blog post.

To provide feedback on these new features in Help Viewer 2.0 Beta:

1. Leave a comment at the bottom of this blog post
2. Send us an email at hlpfdbk@microsoft.com, or
3. Share your thoughts on the Developer Documentation and Help System Forum

Metro style apps

Internet Explorer

Desktop apps

Hardware

As you click through the options in the Center navigation menus, you’ll see familiar MSDN pages (Samples, Downloads, Community, etc.) but with a twist. They’ve been integrated into the Windows Centers so that their branding and navigation is consistent with that of the product.

Library content (under the ‘Learn’ tab instead of the ‘Library’ tab) is also tightly integrated with the Windows Dev Centers and represents a significant departure from the standard MSDN Library.

Why did we create a new, integrated library experience?

The Windows 8 Learn tab provides a specialized version of the MSDN Library devoted to Windows 8 development. It delivers a targeted subset of the content in MSDN and a library search feature that’s constrained to Windows 8 Development topics.

We created this experience to address feedback we’ve received from developers about the challenges they face when using the online MSDN Library.

“It’s great that the MSDN Library has everything, but it’s too hard to find exactly what I’m looking for. It’s like looking for a needle in a haystack.”

There are over 3 million topics in the English language MSDN Library. And, mathematically speaking, about 3 million of those topics are irrelevant to you at any given moment. The Windows 8 Library lets you quickly move a large number of irrelevant topics out of your way so you have a better view of the content that you really need. The Windows Dev Center, at the time of BUILD, reduces the number of topics to about 15,000! Search queries performed inside the Windows 8 libraries will be constrained to those 15,000 topics.

Let’s look at an example of how integrated libraries move unneeded content out of your way. If you’re on the Metro style apps Learn tab and you search for a Win32 API like “CreateWindow” (used by Desktop apps but not by Metro style apps), you’ll get a “No Results Found” notification:

It’s just not there cluttering your life. However, if you truly need to find out more about the CreateWindow API, it’s trivial to remove the Metro style apps refinement and automatically re-issue your query against the entire MSDN Library.

“The table of contents looks too much like a Microsoft org chart. As a result, the information I need is often scattered across the MSDN Library.”

Integrated libraries let us pull relevant content that’s scattered around the MSDN Library into a single experience. For example, we can take patterns & practices phone development guidance and consolidate it with Windows Phone Development content.

“It’s hard to tell one part of the MSDN Library from another and to know which section I’m in, especially when I drop in from a web search.”

Each of the Windows Centers has a unique and easily identifiable URL. Before you’ve even entered a library, you can use the URL listed in search engine results to help determine which result is most relevant. For example:

Once you’re in the library you’ll note that product-specific branding helps you quickly determine where you’ve landed.

Scoped Library Design Principles

Ready for a look under the hood? The integrated Windows 8 Library experience is based on a new capability of MTPS called scoped libraries. A scoped library is a subset of the online MSDN Library with four main components: a reduced set of topics, a search mechanism constrained to those topics, an easily recognized identity (e.g. Windows 8 Development) and a unique, readily identifiable URL path. We’re piloting the Windows scoped libraries and an Azure scoped library to validate that they meet developer needs before adopting them elsewhere in MSDN and TechNet.

I’ve already discussed the benefits of scoped libraries; now let’s review some of the assumptions and principles that governed their design.

1) Every topic in a scoped library is also in the main library

Every topic in a scoped library is also present in the MSDN library. If a developer needs to work with multiple platforms or technologies at the same time, all of that information is available in the master MSDN Library without having to hop around between scoped libraries. The MSDN Library is still your one-stop shop for developer content.

2) As a rule, topics should not appear in more than one scoped library

Since each scoped library topic also appears in the master library, it follows that each scoped library topic can be found at two different URLs: the scoped URL and the master URL. For example, these are the URLs for the “What are Metro style apps?” topic:

Scoped URL: http://msdn.microsoft.com/en-us/library/windows/apps/hh464920.aspx
Master URL:  http://msdn.microsoft.com/en-us/library/hh464920.aspx

Which of these topics is the preferred version? In this case the scoped library topic will be the canonical or preferred version and its URL will receive priority in search engine results.

However, if the same topic is repeated in multiple scoped libraries, we start creating confusion for the user: Why are there so many versions? Are there any differences between versions? If so, which version is the definitive version? Consequently, if a topic must appear in more than one scoped library, the topic in the master MSDN Library will be the canonical URL.

Finally, we provide a way for Microsoft content authors to override the default canonical URL when necessary.

3) Fewer libraries is better

More isn’t necessarily better when it comes to scoped libraries. We don’t want to replace the “needle in the haystack” problem with the “infinite haystacks” problem. Current thinking is that we’ll limit them to our core development platforms (Win8, Azure, Phone, SharePoint, etc.) As we introduce more scoped libraries, we’ll also need to make it possible to discover and navigate between them.

4) Scoped libraries don’t live forever

We expect a typical scoped library to have a lifetime of about three to five years. When a scoped library disappears, the MTPS platform will automatically redirect topic requests to the equivalent topic in the master MSDN Library. Long after attention has moved on to newer platforms, you can still get to the content you need.

The Microsoft Help Viewer 2.0 Developer Preview is now available as part of the Visual Studio 11 Developer Preview. Get the bits at:

• Download Visual Studio 11 Developer Preview (MSDN Subscribers only)
• Download Visual Studio 11 Developer Preview (general availability on September 16, 10am PDT)

Here’s a quick tour of some of the key changes we’ve made from release 1.1 to 2.0 of the Help Viewer.

Setup and Configuration

The first thing you’ll notice is that we’ve removed the “Install Documentation” button from the Visual Studio Setup Finish Page. Too many developers (and Microsoft executives) were missing the “big blue button” during Visual Studio setup. Instead, you’ll be offered the chance to download local help content at Visual Studio first run or when you first set your Help Preference to “Use Local Help.” (Online Help is still the Visual Studio default.)

In addition, you can now set your Help Preference directly from the Visual Studio Help menu.

Content Management

The capabilities of the Help Library Manager have been incorporated into the newly added Help Viewer “Manage” tab. The standalone Help Library Manager is gone. One of the key new features is the ability to relocate your local content store.

If a download is interrupted (for any reason) and restarted by the user at a later time, the Help Viewer won’t re-download any content that has already been transferred. This can save you a lot of time and is especially useful on poor Internet connections. An estimated download size is now displayed before you kick off a transfer to help you better manage bandwidth costs.

Content is downloaded in the background using the Background Intelligent Transfer Service (BITS). You can continue to use the Help Viewer, close the Help Viewer application or even reboot your system once a download has been initiated. When the transfer is complete, the help system automatically updates all help system artifacts (table of contents, search index, keyword index, etc.) without requiring a restart of the Help Viewer.

One other change you’ll see in the viewer is that we’ve added support for dockable windows (something I’ll discuss more in a future post).

Search Filters

The search box now provides search filters. Two filters are supported in the CTP – Title and Code. If you enter “title:foo” in the search box, your search results will be limited to topics that contain the string “foo” in the topic title. If you enter “code:bar”, you’ll get search results limited to topics with the string “bar” in a code example. You can use multiple filters per query and they can be used in combination, for example: “topic:datetime code:datetime code:tryparseexact”.

The Code filter also has a set of sub-filters that enable language-specific searches:

If you want to look for topics that contain the string “foo” in a C# code example, you can search on “code:c#:foo” or “code:csharp:foo”. For example:

New Help Runtime

I’ve saved the best for last. If you look closely, you’ll see that we no longer install the Help Library Agent! The new help runtime has a COM API and the same lifecycle as the Help Viewer. It won’t clutter up your taskbar and it provides improved performance and memory footprint.

But there’s more. Windows 8 incorporates the Visual Studio 11 help runtime API. The Windows 8 “Windows Help and Support” viewer uses the same local help API for content retrieval and the same file and content formats as Visual Studio 11. Because Visual Studio has a need to support down-level operating systems, the help API ships as two different binaries. In Windows 8 it ships as Windows.Help.Runtime.dll and in Visual Studio 11 it ships as Microsoft.VisualStudio.Help.Runtime.dll. The same source code is used to build both DLLs.

In Closing

We spent a lot of time during this release incorporating the runtime into Windows so we didn’t get all of our Help Viewer features done in time for the Developer Preview. In particular, the work we’ve done to incorporate additional filtering features into the Help Viewer won’t be ready until our Beta release.

Please let us know what you think about the Help Viewer 2.0 Developer Preview. As always, you can:

1. Leave a comment at the bottom of this blog post
2. Send us an email at hlpfdbk@microsoft.com
3. Share your thoughts on the Developer Documentation and Help System Forum

(Continue reading about features in the Microsoft Help Viewer 2.0 Beta release.)

• Create and organize a custom collection of Library topics
• Export the collection to a PDF or HTML document
• Print the collection

How do I get started?

There are several prerequisites for using this feature:

• You must be running a browser that implements HTML5 DOM Storage: Internet Explorer 8, Firefox 3.5, Safari 4 or Chrome 5 (or higher versions of these browsers)
• You must be in the Lightweight view of the TechNet Library. Click on the ‘Lightweight’ link in the upper right-hand corner of the Library to change views.
• You need a Windows Live ID

To enable the feature, click the printer icon in the upper right-hand corner of the page and select ‘Print Multiple Topics’ from the drop-down. If you’re running IE8 or higher and you don’t see this option, verify that you’re in Browser Mode IE8 (or higher) and Document Mode IE8 (or higher). You can change these settings under Tools (Alt + X), F12 developer tools.

Read the “Print/Export Multiple Topics – Help” page that appears for instructions on how to use this feature. When you’re ready, click on the ‘Start’ button to begin building a collection. You’ve successfully enabled the feature when the Print Multiple Topics toolbar appears at the top of the page:

How do I create and organize my collection?

The collection is a user-defined subset of Library topics. The collection persists between browser sessions so you can start a collection, shut down the browser, and return to the collection at a later time. The feature currently supports one and only one collection. To create a new collection, you must delete the current collection and start over. At this time the collection cannot be saved or shared.

You add either single topics or entire branches of topics to the collection in one of three ways:

1. While viewing a topic, click on the ‘Add This Topic’ link in the toolbar.
2. Right-click on any topic hyperlink and select ‘Add This Topic’ from the context menu.
3. Right-click on a node in the Table of Contents and select ‘Add This Set of Topics’ from the context menu.
   

At this time, we limit collections to a maximum of 100 topics. As I’ve noted in the past, the Library is large and we don’t want to be responsible for sending three million topics to your printer. The Beta evaluation will help us determine if a 100-topic maximum is sufficient.

When you’re done adding topics to the collection, click on the ‘Collection’ link in the toolbar to open the Manage Collection page.

This page enables you to organize your collection and provides access to the export capability. Topics can be organized in two ways: 1) you can change the order of topics and branches using the drag-and-drop feature of the Manage Collection page, and 2) you can organize groups of topics into chapters.

You can also assign custom names to the collection and its chapters. In the picture above, the collection is named “My Collection” and it has two chapters (PowerShell and SQL Server) that organize the topics. Title and Chapter pages will be added to your collection during the export process.

Finally, your collection persists on the computer on which it was created and is accessible until deleted or until the browsing history is cleared (i.e. cookies, cache, etc.)

How do I export the collection?

Before you can print your collection, you must export it. To export the collection, generate a document in your chosen output format and then download the document to your local machine. Two output formats are supported: HTML and PDF.

1. Click on the ‘Collection’ link in the toolbar to open the Manage Collection page.
2. Review your selections to ensure you’re ready to export.
3. Select an output format. Choose either ‘XHTML’ (HTML) or ‘PDF’ from the dropdown menu.
4. Click on the ‘Generate’ button. If you haven’t already logged in, you will be prompted for your Live ID and then you’ll need to click on the ‘Generate’ button again.
   When you see the “Generating” page your file has been submitted to an Azure service for processing. This page provides status on your Export job. You can wait for your job to complete or continue browsing and return to this page at a later time.
5. When your document is ready, the page name changes to “Finished.” Click on the ‘Download Your Document’ link to download and open the file or right-click on the download link to save the file directly to your hard drive.

How do I print the collection?

Again, you must export the collection before you can print it. HTML files can be printed from your browser, once opened. PDF files can be printed from Adobe Reader.

What are the Advanced Options?

A set of Advanced Options is available on the “Manage Collection” page. These options enable you to add additional Library content to your exported file. Click on the expand icon to the left of the Advanced Options section to reveal these options:

Can I view this content on a Kindle?

Yes. Instructions for transferring PDF files to your Kindle are available on Amazon.com. (Click to view larger image.)

When will this feature be available on MSDN?

We decided to start the Beta program for this feature on TechNet and we’ll expand it to MSDN at a later (to be determined) date. Why? The ability to export Library topics has been a highly requested TechNet feature since IT Pros don’t have the equivalent of the Visual Studio local Help Viewer.

How do I provide feedback on this feature?

We’ll be posting a survey on this feature in the near future but, in the meantime, you can provide feedback by clicking on the Feedback link at the bottom of a Library page or you can leave a comment on this blog.

Let me give you a hint: it’s not right-clicking on a topic in the Help Viewer and “viewing source.” Nor is it cracking open the MSHC files in your local Help Library store. (Although that’s the best approach if you lack access to the Internet.)

As you’d expect, Visual Studio local Help content is just a repackaged version of online MSDN content. Local content is created by running online content through an XSLT transform and then packaging it for distribution. Local help is delivered and updated via the MTPS Service API, a public REST API that exposes MSDN and TechNet Library content. You can use the Service API to find and view raw XHTML files.

Step 1: Determine the ID of the topic you wish to inspect

Locate an online MSDN topic with formatting or behavior you’d like to adopt. The ID of the topic is simply the last segment of the URL and takes one of two forms, a Short ID or an Alias.

• A Short ID is an 8-character combination of letters and numbers. The URL for the “Getting Started with Visual Studio ALM” topic is http://msdn.microsoft.com/en-us/library/dd286491.aspx so its Short ID is dd286491.

• An Alias is a user-friendly replacement for the Short ID. The URL for the “XmlReader Class” topic is http://msdn.microsoft.com/en-us/library/system.xml.xmlreader.aspx where system.xml.xmlreader is the Alias.

Step 2: Use the MTPS Service API to view the topic XHTML

Now that you have an ID, you can use the Service API to view the topic in its original, raw XHTML.

1. Append the ID to the Service API Content URL and open in a browser. The full URL takes the following form (where TopicID can be an Alias or a Short ID):

   http://services.mtps.microsoft.com/ServiceAPI/content/TopicID

2. When you provide a valid ID to the content service, you’ll see a list of Locale/Version combinations. Click on the link for your preferred Locale and Version. (See the MSDN URL Cheat Sheet for more information.)

   To view the EN-US version of the XmlReader Class for .NET Framework Version 4: http://services.mtps.microsoft.com/ServiceAPI/content/b8a5e1s5/en-us;vs.100

3. The page that appears provides a variety of information about your selected topic. Click on the Format:Mtps.Offline link under the Primary Documents heading:

   

4. Right-click and “View source” to inspect the raw XHTML used by the local help system!

Disclaimer

The information in this post is for educational purposes. Both the MTPS Service API and the Help Viewer branding package are intended for use by the Microsoft Help Viewer and are subject to change.

Learn More

MTPS Service API provides a set of web services for exposing the content in MTPS. The URL for Service API is: http://services.mtps.microsoft.com/ServiceAPI

The Service API is documented at: http://services.mtps.microsoft.com/ServiceAPI/docs/

Links

There are three common link types in Help Library content: internal, external and image.

Internal links reference other topics within the local Help Library. They specify link targets by their topic ID alone—an approach we call “identity linking.” Since help topics are referenced without knowledge of their absolute or relative pathnames, topic linking does not depend on the structure of Library content. Why use this approach? The help system separates content, structure, presentation and behavior to enable extensibility and portability to future content formats.

It is the help runtime that maps topic IDs to their corresponding XHTML pages. The help runtime is called via the ms-xhelp API and we reference a specific help system topic by passing its ID into that API. The format of an ms-xhelp URL is:

ms-xhelp:///?Id=Microsoft.Help.ID

Here is an example of how the API is used inside a topic (the class=”mtps-internal-link” markup supports CSS formatting):

External links reference web pages outside of the Help Library and use standard HTTP URLs. Here’s an example of how external links are used inside a topic (the class=”mtps-external-link” markup supports link formatting):

Image links are used to embed images in topics. Embedded images generally reside in the same package (MSHC file) that contains the topic. An example image link:

Branding Package Controls

The appearance and behavior of Help content is defined by a branding package, basically a collection of CSS files, JavaScript, images and other resource files. The help system allows each catalog to specify its own branding package. For this post, we’ll limit ourselves to controls that are provided by the default branding package that ships with the Help Viewer. Using this branding package enables us to easily create topics that look and behave like Visual Studio help content.

The default Help Viewer branding package supports three commonly used controls we’ll look at today: CollapsibleArea, CodeSnippet and LanguageSpecificText.

Collapsible Areas

In Visual Studio Help content, collapsible areas group sections within a topic. They serve two functions: 1) provide formatting for the title of the section, and 2) enable the user to collapse entire sections when reading a topic. This is useful for extremely long topics or for FAQ pages.

Collapsible areas were only partially implemented in Help Viewer 1.x. They provide proper title formatting but they don’t provide a collapse feature. However, marking up your content with the CollapsibleArea tag ensures it can take advantage of this capability in future releases.

The CollapsibleArea control contains the area to be collapsed and specifies the title of the section. For example:

Note that, if Expanded="0", the area starts collapsed. Expanded="1" is the default.

Code Examples (CodeSnippets)

Many Visual Studio help topics contain code examples and syntax documentation. The help system CodeSnippet control displays formatted code examples in the user’s preferred development language. (Note that Help system “CodeSnippets” are not the same as Visual Studio “Code Snippets.”)

The help system automatically groups adjacent code snippets into a “snippet group” that enables readers to easily switch between examples in different development languages. A single CodeSnippet is expressed as follows:

The CodeSnippet control uses two separate tags to support source code formatting. The Language tag specifies the development language used for code colorization. The DisplayLanguage tag specifies the text to be displayed on the snippet tab. Supported tag values include:

Language-specific Text

It is common to use language-specific syntax in help documentation. Because syntax varies from language to language, the help system provides the ability to display text as a function of the reader’s chosen development language. This feature eliminates the need to author separate, redundant topics for each language.

The LanguageSpecificText control displays dynamic text based on the development language selected by the reader using the CodeSnippet control.

For example, the following language-specific text example is used frequently in Visual Studio content to modify namespace delimiters:

And here is the list of supported language tags:

Linking and Code Example Tutorial

Now it’s time to apply what you’ve learned. In this section, you’ll add links and use controls from the Help Viewer branding package to add code examples to your custom topic. This tutorial takes about 5 minutes and makes the following assumptions:

• Visual Studio 2010 (RTM or SP1) is installed on your machine.
• You have administrator privileges on your machine.
• You have successfully used the local Help Viewer to read EN-US help content.

When you’ve completed the exercise, you can remove the tutorial content without side effects to your help system.

Step 1: Create a Topic

To begin, create a folder for your help content and then create a topic in that folder. For the purposes of this tutorial, you’ll create a folder named “HelpTutorial2” in your main Documents folder.

1. Use Windows Explorer to create the folder or from a command prompt:
   mkdir %userprofile%\Documents\HelpTutorial2
2. Launch Notepad.
3. Copy the following XHTML and paste it into Notepad:
   (Tip: If you lose carriage returns when pasting into Notepad, consider copying this XHTML from within Chrome or Firefox. The code examples in this topic will not display correctly if lines don’t break in the correct locations.)

   <?xml version="1.0" encoding="UTF-8"?>
   <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>Links, Code Examples and Language-specific Text</title>
     <!-- Specify the topic content key: ID, locale and version -->
     <meta name="Microsoft.Help.Id" content="ecab3be4-257f-4649-864b-761cfd9510c2" />
     <meta name="Microsoft.Help.Locale" content="en-us" />
     <meta name="Microsoft.Help.TopicLocale" content="en-us" />
     <meta name="Microsoft.Help.TopicVersion" content="100" />
     <!-- Use the default branding package to render the topic -->
     <meta name="Microsoft.Help.SelfBranded" content="false" />
     <!-- Place the topic in the TOC under the root node -->
     <meta name="Microsoft.Help.TocParent" content="-1" />
     <meta name="Microsoft.Help.TocOrder" content="0" />
     <!-- Enable topic access from the keyword index -->
     <meta name="Microsoft.Help.Keywords" content="help content links" />
     <meta name="Microsoft.Help.Keywords" content="Code Example (CodeSnippet)" />
     <meta name="Microsoft.Help.Keywords" content="LanguageSpecificText" />
     <!-- Enable topic access via F1 help -->
     <meta name="Microsoft.Help.F1" content="CodeSnippet" />
     <meta name="Microsoft.Help.F1" content="LanguageSpecificText" />
     <!-- Provide a description for use in the search results list -->
     <meta name="Description" content="This text provides an overview of this topic and is displayed in the search results list." />
   </head>
   <body>
     <h1 class="title">Links, Code Examples and Language-specific Text</h1>
     <div id="mainSection">
       <CollapsibleArea Expanded="1" Title="Content Linking" xmlns="http://msdn2.microsoft.com/mtps">
         <p>There are three common types of links: internal, external and image.</p>
         <table class="members" xmlns="http://www.w3.org/1999/xhtml">
           <tr>
             <th>Type</th>
             <th>Example</th>
             <th>Description</th>
           </tr>
           <tr>
             <td>Internal Link</td>
             <td><a class="mtps-internal-link" href="ms-xhelp:///?Id=1838dc17-b428-4db2-938e-10fa07f63e81">Help System Feature Overview</a></td>
             <td>Internal link to a topic in local Help system documentation</td>
           </tr>
           <tr>
             <td>External Link</td>
             <td><a class="mtps-external-link" href="http://msdn.microsoft.com/en-us/library/default.aspx">MSDN Library</a></td>
             <td>External link to the online MSDN Library</td>
           </tr>
           <tr>
             <td>Image Link</td>
             <td><img class="mtps-img-src" src="image.png" /></td>
             <td>Example of an embedded image</td>
           </tr>
         </table>
       </CollapsibleArea>
       <CollapsibleArea Expanded="1" Title="Language-specific Text" xmlns="http://msdn2.microsoft.com/mtps">
         <p>This text adjusts to match the coding language selected in the SnippetGroup (below).</p>
         <ul>
           <li>Current code language: <strong>
             <LanguageSpecificText devLangcs="C#" devLangvb="VB" devLangcpp="C++" devLangnu="other" xmlns="http://msdn2.microsoft.com/mtps">other</LanguageSpecificText></strong></li>
           <li>Namespace delimiter (example): <strong>XmlReader
             <LanguageSpecificText devLangcs="." devLangvb="." devLangcpp="::" devLangnu="." xmlns="http://msdn2.microsoft.com/mtps">.</LanguageSpecificText>Read Method</strong></li>
         </ul>
       </CollapsibleArea>
       <CollapsibleArea Expanded="1" Title="Examples" xmlns="http://msdn2.microsoft.com/mtps"><a id="exampleToggle" xmlns="http://www.w3.org/1999/xhtml"><!----></a>
         <p>Note that all of the tabs in the SnippetGroup are populated with a code example.</p>
         <!-- Declare the SnippetGroup container -->
         <div id="snippetGroup" xmlns="http://www.w3.org/1999/xhtml">
           <!-- Snippet for the VB language -->
           <!-- Language is the code colorization language -->
           <!-- DisplayLanguage is the tab title language -->
           <CodeSnippet EnableCopyCode="true" Language="VisualBasic" ContainsMarkup="false" DisplayLanguage="Visual Basic" xmlns="http://msdn2.microsoft.com/mtps">
   Imports System
   ' A "hello, world" program in Visual Basic
   Module Hello
     Sub Main()
         MsgBox("hello, world")
     End Sub
   End Module
           </CodeSnippet>
           <!-- Snippet for the C# language -->
           <CodeSnippet EnableCopyCode="true" Language="CSharp" ContainsMarkup="false" DisplayLanguage="C#" xmlns="http://msdn2.microsoft.com/mtps">
   using System;
   // A "hello, world" program in C#
   namespace HelloWorld {
     class Hello {
       static void Main() {
         System.Console.WriteLine("hello, world");
       }
     }
   }
           </CodeSnippet>
           <CodeSnippet EnableCopyCode="true" Language="ManagedCPlusPlus" ContainsMarkup="false" DisplayLanguage="Visual C++" xmlns="http://msdn2.microsoft.com/mtps">
   // A "hello, world" program in C++
   main( ) {
     printf("hello, world");
   }
           </CodeSnippet>
           <CodeSnippet EnableCopyCode="true" Language="FSharp" ContainsMarkup="false" DisplayLanguage="F#" xmlns="http://msdn2.microsoft.com/mtps">
   // A "hello, world" program in F#
   #light
   open System
   printfn "hello, world"
           </CodeSnippet>
           <CodeSnippet EnableCopyCode="true" Language="JScript" ContainsMarkup="false" DisplayLanguage="JScript" xmlns="http://msdn2.microsoft.com/mtps">
   // A "hello, world" program in JScript
   print("hello world");
           </CodeSnippet>
         </div>
         <p>Singleton with tab and language colorization:</p>
         <CodeSnippet EnableCopyCode="true" Language="html" ContainsMarkup="false" DisplayLanguage="XHTML" xmlns="http://msdn2.microsoft.com/mtps">
   &lt;html xmlns="http://www.w3.org/1999/xhtml"&gt;
     &lt;head /&gt;
     &lt;body&gt;
       &lt;p&gt;hello, world&lt;/p&gt;
     &lt;/body&gt;
   &lt;/html&gt;
         </CodeSnippet>
         <p>Singleton with no tab, no colorization:</p>
         <CodeSnippet EnableCopyCode="true" Language="other" DisplayLanguage="" ContainsMarkup="false" xmlns="http://msdn2.microsoft.com/mtps">
   HRESULT SetDeviceEnumPreference(
     [in]  DWORD dwEnumPref
   );
         </CodeSnippet>
       </CollapsibleArea>
     </div>
   </body>
   </html>
   

4. Save the file as: %userprofile%\Documents\HelpTutorial2\topic2.html
5. Close Notepad.
6. Right click on the MSDN image below and “Save picture as…” image.png in the HelpTutorial2 folder.
   

Step 2: Create a Package

Next, place your topic in a package.

1. In Windows Explorer, right click on the topic2.html file you created in Step 1 and send it to a Compressed (zipped) folder named mycontent2.zip.
   
2. Drag image.png into the mycontent2.zip folder.
3. Rename the mycontent2.zip folder to mycontent2.mshc. (Click ‘Yes’ on the Rename dialog that pops up.)

Step 3: Create a Book

The last step in preparing your content is placing your package in a “book”. As you’ll recall from my previous post, a book is a collection of packages and is defined in an asset manifest file named HelpContentSetup.msha.

1. Launch Notepad.
2. Copy the following XHTML content and paste it into Notepad:

   <html xmlns="http://www.w3.org/1999/xhtml">
     <head />
     <body class="vendor-book">
       <div class="details">
         <span class="vendor">My Company</span>
         <span class="locale">en-us</span>
         <span class="product">My Custom Content</span>
         <span class="name">More Custom Topics</span>
       </div>
       <div class="package-list">
         <div class="package">
           <span class="name">mycontent2</span>
           <span class="deployed">true</span>
           <a class="current-link" href="mycontent2.mshc">mycontent2.mshc</a>
         </div>
       </div>
     </body>
   </html>
   

3. Save the file as:
   %userprofile%\Documents\HelpTutorial2\HelpContentSetup.msha
   (Tip: Set the “Save as type” dropdown list in Notepad to “All Files (*.*)” )
4. Close Notepad.

Step 4: Install the Book

Launch the Help Library Manager in administrative mode and install the book from disk. If you’re unsure how to do this, follow the install instructions from my previous post.

Step 5: Explore Your Content

Select “View Help” from the Visual Studio Help menu. Note that your topic appears in the Table of Contents as a child of the root node:

If you select this topic you’ll see the following page:

To Learn More

This tutorial covers the basics of the Visual Studio Help Viewer branding package. To learn more about designing content for the Microsoft Help Viewer, check out these resources:

• The Help Viewer 1.0 SDK goes into greater detail on how to create, brand and deploy content.
• For more complex projects, I highly recommend using a help authoring tool.
• The Help Guy blog is a good resource for anyone creating Help Viewer content.
• Microsoft Help MVP Rob Chandler has assembled a nice overview of Microsoft Help Viewer 1.0.

• Visual Studio 2010 (RTM or SP1) is installed on your machine.
• You have administrator privileges on your machine.
• You have successfully used the local Help Viewer to read EN-US help content.

Step 1: Create a Topic

The basic unit of content in the help system is a “topic”. A topic is a single piece of XHTML content with a unique identity in the local Help Library.

To begin, create a folder for your help content and then create a topic in that folder. For the purposes of this tutorial, you’ll create a folder named “HelpTutorial” in your main Documents folder.

1. Use Windows Explorer to create the folder or from a command prompt:
   

   mkdir %userprofile%\Documents\HelpTutorial

2. Launch Notepad.
3. Copy the following and paste it into Notepad:

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>My Custom Content</title>
  <!-- Specify the topic content key: ID, locale and version -->
  <meta name="Microsoft.Help.Id" content="b3382805-aa6b-4e6f-a346-73d20f74d0cd" />
  <meta name="Microsoft.Help.Locale" content="en-us" />
  <meta name="Microsoft.Help.TopicLocale" content="en-us" />
  <meta name="Microsoft.Help.TopicVersion" content="10" />
  <!-- Use the default branding package to render the topic -->
  <meta name="Microsoft.Help.SelfBranded" content="false" />
  <!-- Place the topic in the TOC under the root node -->
  <meta name="Microsoft.Help.TocParent" content="-1" />
  <meta name="Microsoft.Help.TocOrder" content="0" />
  <!-- Enable topic access from the keyword index -->
  <meta name="Microsoft.Help.Keywords" content="my custom content" />
  <!-- Enable topic access via F1 help -->
  <meta name="Microsoft.Help.F1" content="myTopic" />
  <!-- Provide a description for use in the search results list -->
  <meta name="Description" content="This text provides an overview of this topic and is displayed in the search results list." />
</head>
<body>
  <h1 class="title">My Custom Content</h1>
  <div id="mainSection">
    <p>This is an example of a simple, well-formed library topic.</p>
  </div>
</body>
</html>

4. Save the file as: %userprofile%\Documents\HelpTutorial\topic1.html
5. Close Notepad.

Interlude: Anatomy of a Topic

In this segment, we’ll look more closely at the topic you just created. If you want to load your topic into the local Help Library as quickly as possible, skip to Step 2: Create a Package to continue on with the tutorial.

First and foremost, our topic needs to be a well-formed XHTML Basic 1.1 topic that can be consumed by the .NET Framework XmlReader class. All tags must be properly closed and you must use the correct HTML encoding for symbols and special characters.

Our text-only content is located between the <body> tags. We want the same look-and-feel as the Visual Studio documentation so we’re using the standard “branding package”. This branding package will format our topic correctly if it includes the following markup:

• Add class="title" in the topic heading tag
• Place the body text inside a <div> with id="mainSection"

<body>   <h1 class="title">My Custom Content</h1>   <div id="mainSection">     <p>This is an example of a simple, well-formed library topic.</p>   </div> </body>

Now let’s look at the metadata in our topic. The purpose of this metadata is to enable discovery and navigation of help system content. The metadata is specified using standard <meta> tags located in the <head> section of the topic.

The <title> tag determines how the topic is displayed in the Table of Contents (TOC). Note that, while the system enables the topic title to be different than the topic’s H1 heading, it is customary for them to be identical.

<title>My Custom Content</title>

In the help system, a topic’s identity (called the “content key”) consists of the topic ID, topic version and topic locale. The content key enables the same topic to exist in multiple documentation versions and multiple human languages. It is important for the Microsoft.Help.Id meta tag value to be unique within the help system. While this can be set to any string value, it is customary to use a GUID to ensure uniqueness across content from multiple vendors. The Microsoft.Help.Locale meta tag tells the indexer which word breaker to use when parsing the topic for search terms. If this tag is omitted, the help system defaults to the word breaker associated with the Windows operating system locale setting. The Microsoft.Help.TopicLocale meta tag enables the system to distinguish between different locale versions of the same topic, for example, when both English (EN-US) and Japanese (JA-JP) content are both present in the local Help Library. Finally, we set the topic version to content="10" since this is Version 1.0 of our topic.

<!-- Specify the topic content key: ID, locale and version --> <meta name="Microsoft.Help.Id" content="b3382805-aa6b-4e6f-a346-73d20f74d0cd" /> <meta name="Microsoft.Help.Locale" content="en-us" /> <meta name="Microsoft.Help.TopicLocale" content="en-us" /> <meta name="Microsoft.Help.TopicVersion" content="10" />

The look-and-feel of the topic (font, color, spacing, behaviors, etc.) is specified by our branding package. Creating a custom branding package is outside the scope of this tutorial so we’ll just use the standard branding package that ships with Visual Studio. Note that the standard branding package is used by default so this tag is optional and is included here for completeness.

<!-- Use the default branding package to render the topic --> <meta name="Microsoft.Help.SelfBranded" content="false" />

Normally, we’d set the value of the Microsoft.Help.TocParent meta tag to the Microsoft.Help.Id of another topic. This establishes our position in the TOC hierarchy. In this case, we want the topic to appear as a child of the TOC root node and to do that we set content="-1". The Microsoft.Help.TocOrder tag tells the system how to order our topic relative to its peers. Children of the root node sort by TocOrder first, then by topic ID. All other nodes in the TOC sort by TocOrder first, then by title, then by topic ID.

<!-- Place the topic in the TOC under the root node --> <meta name="Microsoft.Help.TocParent" content="-1" /> <meta name="Microsoft.Help.TocOrder" content="0" />

We want the topic to be discoverable from the keyword index and we’ll use the Microsoft.Help.Keywords tag to do this. Multiple index entries can be specified by repeating this tag. For best results, keyword index strings should be highly related to this specific topic.

<!-- Enable topic access from the keyword index --> <meta name="Microsoft.Help.Keywords" content="my custom content" />

We also want this topic to be accessible from F1 Help inside the Visual Studio IDE. We’ll use the Microsoft.Help.F1 to assign our F1 Help string. The F1 string must be highly related to this specific topic to enable an unambiguous F1 help query.

<!-- Enable topic access via F1 help --> <meta name="Microsoft.Help.F1" content="myTopic" />

Finally, we specify a user-friendly description of this topic. The topic description is displayed, along with the topic title, in the search results pane.

<!-- Provide a description for use in the search results list --> <meta name="Description" content="This text provides an overview of this topic and is displayed in the search results list." />

In Help Viewer 1.x, all of the help system artifacts (table of contents, search index, keyword index, etc.) are generated from topic metadata. Because of this, it is important that topics are well-formed and contain appropriate meta tags to behave well inside the help system. The Help Viewer 1.0 SDK provides a more complete treatment of help system meta tags.

Step 2: Create a Package

Now that you have a topic, it’s time to place that topic in a “package”. A package is a collection of topics and their associated resources (images, scripts, etc.). Packages are ZIP files with an .MSHC extension.

The help system was designed to scale to extremely large libraries. Some of the Visual Studio content sets have almost 200,000 topics. Packages are used to break up these content sets into smaller chunks that are used to transport content from an online endpoint to the end-user’s hard drive. By convention, packages include no more than 10,000 topics.

Placing your topic in a package is simple:

1. In Windows Explorer, right click on the topic1.html file we created in Step 1 and send it to a Compressed (zipped) folder named mycontent.zip.
2. Rename the mycontent.zip folder to mycontent.mshc. (Click ‘Yes’ on the Rename dialog that pops up.)

Step 3: Create a Book

The last step in preparing your content is placing your package in a “book”. A book is a collection of packages and is defined in an asset manifest file named HelpContentSetup.msha.

Content is added to or removed from the local Help Library one book at a time. Even if you only want to add a single package to the local Help Library you must place it in a book. If packages are the unit of transport, you can think of books as the unit of install.

In this tutorial, you’ll use the following settings:

You supply the help system with information on how to display your new book in the Help Library Manager by creating an asset manifest (.MSHA) file.

1. Launch Notepad.
2. Copy the following XHTML content and paste it into Notepad:

<html xmlns="http://www.w3.org/1999/xhtml">
  <head />
  <body class="vendor-book">
    <div class="details">
      <span class="vendor">My Company</span>
      <span class="locale">en-us</span>
      <span class="product">My Custom Content</span>
      <span class="name">My Custom Topics</span>
    </div>
    <div class="package-list">
      <div class="package">
        <span class="name">mycontent</span>
        <span class="deployed">true</span>
        <a class="current-link" href="mycontent.mshc">mycontent.mshc</a>
      </div>
    </div>
  </body>
</html>

3. Save the file as:
   %userprofile%\Documents\HelpTutorial\HelpContentSetup.msha
   (Tip: Set the “Save as type” dropdown list in Notepad to “All Files (*.*)” )
4. Close Notepad.

Step 4: Install the Book

You should now have the two files that make up your book in the HelpTutorial directory: mycontent.mshc and HelpContentSetup.msha.

In Version 1.x of the Microsoft Help Viewer, local help content is added, updated and removed from the Visual Studio 2010 local Help Library with the Help Library Manager (HLM). HLM can be launched with command line parameters that will help you get the job done.

1. Launch a command prompt with administrator privileges. Administrator privileges are required when a book is not wrapped in a digitally signed CAB file. (More on that later.)
   
2. From the prompt, change to the location of the HLM utility:
   

   cd %programfiles%\microsoft help viewer\v1.0

3. From the prompt, instruct Help Library Manager to add your book to the Visual Studio help catalog:

   HelpLibManager.exe /product VS /version 100 /locale en-US /sourceMedia %userprofile%\Documents\HelpTutorial\HelpContentSetup.msha

4. Click on the ‘Add’ link. (Note that the size is an estimate of the book size and is rounded up to the nearest megabyte.)
5. Click on the ‘Update’ button.
6. At this point, the system requests permission to proceed because the book is not wrapped in a digitally signed CAB file. Click on the ‘Yes’ button.
7. The help content in this tutorial was not pre-indexed so the system automatically creates the necessary search indexes. Wait for the index merge to complete.
8. Click on the ‘Finish’ button.

You’re done! Note that the only tools you needed were a command prompt, Notepad, Windows Explorer and Help Library Manager. And every component of your work could be inspected with either Notepad or a web browser.

Step 5: Explore Your New Content

Take your new content for a test drive. Launch Visual Studio 2010 and select “Manage Help Settings” from the Help menu. In Help Library Manager, select “Choose online or local help” and verify that your preferred help experience is set to “I want to use local help.”

Now “Check for updates online” and confirm that the new book appears in your content list.

Cancel out of HLM and select “View Help” from the Visual Studio Help menu. Note that your topic appears in the Table of Contents as a child of the root node just as you specified in the Microsoft.Help.TocParent meta tag.

Switch to the Index tab and enter “my custom content” in the index search box. You specified this index item in the Microsoft.Help.Keywords meta tag. Clicking on the index item takes you to your topic.

Type Ctrl + E to go to the Help Viewer search box and enter “My Custom Content”. While the exact position of the topic in the result list will vary depending on the content you’ve installed, you should see it on the first page of search results.

Close the Help Viewer and open a code editor in Visual Studio. Type “myTopic”, highlight “myTopic” and press the ‘F1’ key. Help Viewer should open to your newly installed topic. You specified the topic’s F1 value in the Microsoft.Help.F1 meta tag.

How do I remove the book from my Help Library?

Launch HLM and select “Remove Content”. Click on the Remove link corresponding to My Custom Topics.

Can I distribute my book to other people?

Yes. However, if you want to eliminate the security alert dialog during install and make your content accessible to non-administrators, you’ll need to place your book in a signed .CAB file.

To Learn More

This tutorial covers the mechanics of creating a simple text-only book. I haven’t discussed topic linking, using controls or custom branding. To learn more about designing content for the Microsoft Help Viewer, there are a number of resources available:

• The Help Viewer 1.0 SDK goes into greater detail on how to create, brand and deploy content.
• For more complex projects, I highly recommend using a help authoring tool.
• The Help Guy blog is a good resource for anyone creating Help Viewer content.
• Microsoft Help MVP Rob Chandler has assembled a nice overview of Microsoft Help Viewer 1.0.

Open Control Panel\Programs\Programs and Features to verify your version of Help Viewer. After successfully installing Visual Studio 2010 SP1, you will see an entry that looks like this:

While it can be accessed directly from the Visual Studio Help | Manage Help Settings menu item, the Help Library Manager is really a component of the Help Viewer.  In SP1, Help Viewer 1.1 still ships Help Library Manager 1.0.  You will see this on the Help Library Manager dialog box:

This is expected behavior and does *not* indicate a problem with your upgrade.

Why did we do this? We decided not to modify Help Library Manager in Service Pack 1 so we could focus on the customer feedback on our local help experience. As a result, the Help Library Manager dialog still displays a Help Viewer 1.0 version.

The Library is huge and teams across Microsoft publish new content into it regularly. In order to make that information available worldwide and in a timely manner, we use a combination of human translation and automated translation (translation memory + machine translation). For a variety of reasons it is often useful to view translated content alongside its original English version.

Introducing the bilingual display feature

The February 2011 release of the MSDN and TechNet Libraries delivered a bilingual display feature. This feature enables you to easily switch back and forth between the translated version of a topic and the original English version. There are two main design elements: 1) a control banner and 2) translation hover text.

The control banner only appears when the current topic is authored as bilingual content. It appears and disappears on a topic-by-topic basis. The banner informs the reader whether the topic has been translated by a human or by machine and offers brief usage instructions. For example: “This is machine translated content. Move your pointer over text in the content pane to see the original text. Help improve the translation.”

Using the bilingual display is straightforward. When the banner is displayed at the top of the topic:

1. Use the control banner to select whether you wish to read the topic in the translated language or in the original English. Your selection persists across topics and browser sessions. This choice does not override your preferred locale for reading the library. It affects only the behavior of the bilingual display.
2. Position the mouse pointer over any sentence. If you’re reading the topic in a translated language, the original sentence will display in hover text. If you’re reading the topic in English, the translated sentence will display in hover text.

Here are some examples to play with:

• MSDN: System.Xml Namespace – German (Germany)
• MSDN: XmlDocument Class – Portuguese (Brazil)
• TechNet: Overview (Database Engine) – Polish (Poland)
• MSDN: System.Xml Namespace – Japanese (Japan)
• MSDN: System.Xml Namespace – Russian (Russia)

Like a tooltip, the translation hover text only provides help when you need it. The entire content pane is devoted to displaying the topic in your preferred reading language. Our goal is to ensure that it’s easy to consume the content either reading the translation (augmented by the source) or reading the source (augmented by the translation). An added benefit of this approach is that it supports the numerous page layouts used throughout the Library.

How many topics offer a bilingual display?

The MSDN Library provides over 13 million translated topics – roughly 80% of the total Library content. Of those, about 4 million are published in a bilingual format distributed across 14 supported locales:

As you can see, bilingual content currently makes up the majority of content in our Arabic (Saudi Arabia), Czech (Czech Republic), Portuguese (Brazil) and Turkish (Turkey) libraries. Most of this content is in the Visual Studio / .NET Framework product documentation at this point. I expect more and more of the Library content to be authored for bilingual consumption in the future.

Note: At this time, right-to-left (RTL) languages are not supported in Lightweight. Bilingual content in those languages will display in the older, Classic view.

What if I want to suggest a better translation?

The Lightweight Library view does not yet support the ability to suggest a better translation. To do this, you’ll need to use the Translation Wiki capability of the Classic MSDN Library where available. Currently you can edit Visual Studio and .NET Framework content for Arabic, Brazilian Portuguese, Czech, and Turkish. We expect to deliver community translation capabilities in a future release of the MSDN/TechNet Library and I will blog about it when we do.

• Navigate the table of contents in a fully expandable tree control
• Look up topics via keyword index and sync to the table of contents
• Save favorites
• View history
• Use shortcut keys for quick access to features (cheatsheet here)
• Launch the Help Library Manager from within the viewer

The local viewer requires that your help preference is set to local mode.  Visual Studio continues to provide help in your default browser if your help preference is set to online.

Here are the steps you’ll need to take to set up the SP1 local viewer.

Step 1: Install Visual Studio 2010 SP1

Download Visual Studio 2010 SP1 and follow the installation instructions.

• Download Service Pack 1 (MSDN Subscribers only)
• Download Service Pack 1 (public availability on Thursday, March 10)

SP1 will upgrade previous versions of the Microsoft Help Viewer to version 1.1 and it will uninstall the Help Viewer Power Tool (if present).  It will not, however, replace any third-party help applications you may have installed.

Step 2: Configure the local Help Viewer

1. Launch Visual Studio 2010 and select “Manage Help Settings” from the Help menu.
2. In Help Library Manager, select “Choose online or local help” and set your preferred help experience to “I want to use local help.”
3. If you have not already downloaded help content, select “Install content from online” in Help Library Manager and choose the content you want locally available.

If you’re currently using a third-party viewer and you wish to switch to the SP1 local viewer, you have several options.  In the specific case of H3Viewer, you can change the default viewer in the Options menu.  Another option is to uninstall the third-party viewer using the Control Panel.  You can do this before or after installing SP1.  Once the third-party viewer is successfully uninstalled, the SP1 viewer automatically becomes the help experience for Visual Studio 2010.

A more advanced option is to remove the registry setting that configures the third-party viewer as the default help viewer.  To do this, you’ll:

1. Launch Regedit with administrative privileges and browse to: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v1.0
2. If the HelpViewerProgID entry exists, right-click it and delete it

Please remember to backup your registry (or create a System Restore point) before performing this operation.

Providing feedback on this viewer

A key goal of this release is to restore productivity for developers who were skilled at using the Document Explorer while providing a user interface that is more approachable for new customers of Visual Studio.  How did we do?

There are a number of ways you can provide feedback on the local viewer:

• Report a bug or suggest a feature by logging into Connect using your Windows Live ID.  Connect feedback is routed directly to our engineering team and is reviewed during our daily triage meetings.
• Send us an email at hlpfdbk@microsoft.com
• Share your thoughts on the Developer Documentation and Help System Forum, or
• Leave a comment at the bottom of this blog post

Finally, to learn about other changes in SP1, check out Jason Zander’s SP1 announcement post.