Introduction

Many Windows SDK users have questions about the system behind the documentation provided with the SDK.  Here is the first in a series of posts explaining how this system works and how to customize it.  This post provides an overview of the basic structure behind the Windows SDK help system.  It also looks at how ms-help:// URLs can be used to learn about the organization of the documentation “behind the scenes.”  Look for part 2, which will explain the mechanism behind the table of contents (TOC), and show you how to customize it.

Explanation of Help Services and the Viewer

There are two major pieces to the documentation that ships with the Windows SDK.  The first is a set of help services (called Help 2.0).  These services allow us to create namespaces for holding sets of documentation, register documentation files (.HXS files) to those namespaces, and provide that content to the customer by servicing requests from URLs in the form ms-help://

The second big piece is the viewer.  The viewer that ships with the Windows SDK currently is DExplorer 9.0.  DExplorer has been around for quite a long time.  It is the application that launches when you click the icon for Windows SDK documentation in the start menu. 

These two pieces, the help services and the DExplorer viewer, make up the primary offline help experience for Microsoft.  It is used by many teams across the company, including MSDN, SQL Server, and of course the Windows SDK.

Windows SDK Namespaces

Different product units use different schemes for their documentation.  For the Windows Server 2008 SDK, we chose to organize our documentation into three namespaces.  The first, MS.LHSMSSDK.1033, is our root “parent” namespace.  It is mostly empty, containing only introductory topics about the SDK and some API catalog information.  The second, MS.LHSNETFX30SDK.1033, contains our “managed” content, topics aimed toward the .NET developer.  The third, MS.LHSWINSDK.1033, contains the “native” content, topics aimed toward the Win32 and COM developer.  This is how we allow the user to only install the Win32 and COM documentation, .NET Framework documentation, or both.  At installation time, we always install the parent node, and then install and plug-in the appropriate children depending on the user’s selections.

clip_image001

Deciphering ms-help URLs

When paying attention to the URL box toward the top the documentation in DExplorer, the user can learn more about where topics live in the documentation system.  From the URL users can determine not only which HXS file contains each topic, but which namespace the HXS file is registered to.  This will help later in figuring out how to customize the TOC.

clip_image002

URLs for the SDK are almost always in the form:

ms-help://MS.LHSMSSDK.1033/<hxsname>/…
Or
ms-help://MS.LHSMSSDK.1033/<child namespace>/<hxsname>/…

For instance, open the SDK documentation, expand the Win32 and COM node, expand the Administration and Management node, expand the Application Installation and Servicing node, then click on the Application Recovery and Restart node. 

clip_image002[6]

Observe that the URL is:

ms-help://MS.LHSMSSDK.1033/MS.LHSWinSDK.1033/recovery/recovery/portal.htm

This URL tells us the topic lives in recovery.hxs, which belongs to the MS.LHSWINSDK.1033 namespace, which is a child of the master MS.LHSMSSDK.1033 namespace as outlined earlier.

Conclusion

Hopefully this basic overview of what is going on “behind the scenes” with the Windows SDK documentation is helpful.  A basic understanding that the help system is made up of a set of services and a viewer to those services can help troubleshoot problems with the documentation.  Being able to look at a help URL and understand something about the way files and topics are organized can help users better see the structure.

In a future post, we’ll take this basic information and use it to make TOC customizations.  With some additional information, reorganizing the table of contents is easy and can help users quickly get to the content they use most often.

Mike Johnson
Software Development Engineer in Test

The MSDN Windows SDK Developer Center is the place to find resources and links to Windows SDK products, release notes, technical articles, and more.