Create a basic help file for the Microsoft Help Viewer

In this post, I’ll show you how to create some simple content and add it to the Visual Studio local Help Library. The only tools you’ll need are a command prompt, Notepad, Windows Explorer and the Help Library Manager. This exercise takes about 5 minutes and, when you’re done, you can easily remove the content without any side effects to your help system. This tutorial 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.

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>
  1. Save the file as: %userprofile%\Documents\HelpTutorial\topic1.html
  2. 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.sendtozip
  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:

Vendor: My Company
Product: My Custom Content
Locale: EN-US
Book Name: My Custom Topics

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>
  1. Save the file as:
    %userprofile%\Documents\HelpTutorial\HelpContentSetup.msha
    (Tip: Set the “Save as type” dropdown list in Notepad to “All Files (*.*)” )
  2. 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.

bookfolder

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.)
    cp-admin
  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.)install1
  5. Click on the ‘Update’ button.install2
  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.install3
  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.install4
  8. Click on the ‘Finish’ button.install5

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.

bookinstalled

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.

topicintoc

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.

topicindex

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.

topicsearch

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.

topicf1

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.

How do I create MSDN-style content?

OK, you’ve successfully added a topic to your local Help Library but that topic isn’t very interesting. If you want to add links and MSDN-style controls (code examples, collapsible areas and language-specific text) to your content, check out my post on adding links and code examples to help topics you create.

To learn more about creating and branding content for Microsoft Help Viewer 1.x, check out these resources:

Posted in Microsoft Help Viewer, Visual Studio 2010 | Tagged , , | Comments closed

Help Viewer 1.1, Help Library Manager 1.0

“I just installed SP1 and still see Help Viewer 1.0, not 1.1. Which version do I have?”

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:

hv1-1arp

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:

hlmver

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.

Posted in Microsoft Help Viewer, Visual Studio 2010 | Tagged , , | Comments closed

View translated content alongside English in the Lightweight Library

I’d like to extend a special greeting to those of you who read the MSDN and TechNet Libraries in a non‑English language. You represent 25% of our overall site traffic – about 60 million page views per month.

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.

bilingual-display

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:

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:

bilingual-content

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.

Posted in MSDN Library, TechNet Library | Tagged , | Comments closed

New local help viewer available in Visual Studio 2010 SP1

The new local help viewer I’ve been blogging about is now available with Visual Studio 2010 Service Pack 1. MSDN subscribers may download SP1 immediately with general availability on Thursday. Microsoft Help Viewer 1.1 is a dedicated client application that lets you:

  • 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

HV1-1

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.

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:

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

This post is available in the following translations:

Posted in Microsoft Help Viewer, Visual Studio 2010 | Tagged , , , | Comments closed

Quick Links on the MSDN Library home page

While most of the MSDN Library traffic comes in from search engines, about 220,000 pageviews/month enter from a direct link to the MSDN Library home page. In the recent past the home page has looked like this:

before

Traffic analysis showed that very few people were clicking on the links in this page. The page just didn’t have high value and seemed to be primarily used as a bookmark for performing an MSDN site search.

The team believed we could make this high-traffic page more valuable to users.  We wanted to make it easier for visitors to the Library home page to discover popular and important content. So, this month, we rolled out a Beta of a new Quick Links page:

quicklinks

Links are grouped by platform and enable discoverability of and easy-access to important technologies and overview topics. Let’s zoom in on the Desktop development section.

linktypes

Note that there are three types of Quick Links:

  1. Platform hubs – Title links group the rest of the links by development platform.  Clicking on one will take you to its corresponding MSDN Hub page.
  2. Key technologies – Bolded links provide quick access to commonly-used platform technologies.
  3. Overview topics – These links take you to topics that help you start using a technology quickly: API Reference, Code Samples, How Tos and Walkthroughs.

Is this a better use of our Library Home Page? Provide feedback on the Quick Links Beta.

(Special thanks to J.D. Meier who helped us with our information architecture.)

Posted in MSDN Library | Tagged | Comments closed

Help MVPs in town for 2011 MVP Summit

Microsoft Help MVPs were in town last week for the 2011 MVP Summit.  Attending this year were:

MVP Summit 2011

Front row, from left: Paul, Rob, Char, Paul O’Rear (MSFT) and Dana
Back row: Not our Help MVPs!

The Library Experience team spent a day and a half with the Help MVPs reviewing the current help system and our future plans. We also had a surprise visit from the inimitable Ralph Walden. Paul O’Rear (LEX team Community Lead and The Help Guy) coordinated and led our part of the summit.

The Help MVPs keep us honest and remind us that there is more to the Help ecosystem than just Visual Studio help. Among other things, I learned about the American Society for Indexing. On behalf of the entire team, thanks so much for making the trip to Redmond and spending time with us!

Now what can we do to top this year’s summit? Guess I’ll have to work on that…

Posted in Microsoft Help Viewer, MSDN Library | Tagged , , , | Comments closed
%d bloggers like this: