The D-word

Documentation. Good documentation is seldom seen. We all know the nDoc tool that can massage our code comments into a nice looking reference document. But just reference documentation is usually not sufficient. You probably know from your own experience that learning to master a new library or framework takes more than just reference documentation if you want to avoid endless trail and error and searching for that API call that does what you need at that time. You need an overview of the architecture (code design) in order to relate different classes to eachother. You need a description of common usage patterns so you can get started quickly. You need… well, good documentation.

I’m not going to write about what I think is good documentation, I leave that to you to work out ;-). I just want to bring a help authoring tool under your attention that I’ve been missing (like for ever). It is packaged in an unexpected place: the Visual Studio 2005 SDK (VSIP). This SDK you use when you want to extend Visual Studio. You need to register to get it here. Microsoft ships a stripped down version of HelpStudio called HelpStudio Lite made by Innovasys. If you ever worked with Html Help workshop that ships with Visual Studio for some time now, you will find the tool familiar, if you do not have any experience, just take a look at an existing Help file and you will get most of the concepts in no time. The tool will let you generate help content that integrates into the VS.NET help viewer.

When installation of the VS.NET SDK is finished the following screen is shown. Notice that the Help Authoring tool is not installed by default and has to be installed seperatly. When I ran the installation it looked as if it didn’t work, no progress indication or whatever, but eventually the installer reported a succesfull install. So be patient.

Visual Studio SDK Installer - HelpStudio Component

When you start HelpStudio Lite a startup window is shown by default, explaining how to create a new project for instance. When creating a new project you get a choice for VS 2003 or VS 2005 compatibility. The following screenshot shows you a new help project in HelpStudio Lite.

HelpStudio New Project

Looks better that Html Help Workshop doesn’t it. I would suggest you try it and see for yourself.

nDoc Documentation

One of the things you probably want to do (at least I wanted to do) is integrate the html files generated by nDoc into your HelpStudio project. nDoc uses Html Help Workshop under the covers and HelpStudio Lite allows an import of a Html Help Workshop project file. Sweet. Not entirly. All content is wrapped in the selected HelpStudio template and this will give you double (contained) headers on each and every page. The Solution I found that works best is only import the Table of Content (ToC) of your nDoc result and just hand copy all html files into the build directory (called Default). You could add each html file to the HelpStudio project definition, but that gets labour intensive when handling large numbers and frequent updates. Each imported ToC entry has a link to an .htm file and those will get resolved during the build or you will get errors. You can move the imported ToC around to any place you fancy, without breaking the links to the content.


So you’re done. Now you want to package your help file so others can install it (together with your library or framework). Unfortunatly the help system is pretty complex and it is not a case of just distributing a help file (like .chm). The Vistual Studio SDK site has a installer for a new VS.NET Project type that lets you build a help deployment setup (and merge module). It is called Help Integration Wizard and can be downloaded here. When you create a new VS.NET project of this type you walk through a wizard that lets you browse to the help file built by HelpStudio and create an installer for it. Note that when installing help files registering the help collection takes really long.

So I hope you find this usefull and I helped inspire you to write ‘good documentation’. This description is not as detailed as I would like due to time contraints. If you have any questions just post them as comments and I will try to get you started.

TIP: Did you know that you can export VS.NET 2005 class diagrams as .jpg image files? Right click in the designer and choose the export menu option. Now you can inculde class diagrams easily in your help files, point to the Image Files folder, add them to the help project and drag & drop them into your help Topic.