Friday, July 20, 2007

Who builds this stuff?

No matter what system you run there are areas that just don't make any sense.  I love Visual Studio and will argue with anyone that it's the best way to develop traditional platform applications.  That being said, it's help system is quite ridiculous.

You would think that a company that is so focused on developer productivity would make it trivial to integrate third-party documentation.  The pages of the documentation are all just HTML files.  Each documentation package might contain some indexes but on the whole it's just HTML.  Here's an idea.  Just make the help format a zip archive and inside this zip you layout the HTML in whatever tree structure you like.  Include whatever scripts, CSS, or binary content you like.  Any top level pages that should not appear in the TOC can be listed in some .exclude file.  There can be a file that lists the name to file indexes.  All of this could then be neatly compressed inside a zip archive.

Anyway, I didn't  use Robohelp or any other commercial product.  Instead I used Sandcastle and the excellent NDoc replacement Sandcastle Help File Builder.  This tool works with the latest Sandcastle bits and builds both CHM and HxS style help files.  While SHFB allows me to integrate additional HTML content, the current version ( has a bug that keeps it from being able to generate a root namespace.  I wanted my namespace documentation to be listed under a node named 'Reference'.  Luckily this project is open source and Eric has already made available a patch that fixes this issue.

The next problem was that the normal VS2005 Help Merge Module project would not integrate the generated HxS correctly.  I tried other Sandcastle generated files and they worked ok but mine simply refused.  I would up using the terrific FAR tools to hand tweak the collection files to get my table of contents working right.

The next thing I have to work on is integrating the Connector/Net portions of our online manual.  I've already discussed this with our docs team and we think we have an approach.  Wish us luck.  ;)


  1. Congratulations, with your "HTML files in ZIP archive" you've just invented Borland's JBuilder help/manuals format.

    I do believe that adding to the IDE's help should be simple and straightforward.

  2. Hey, I've always thought Borland made excellent products. Like so many, I cut my teeth on Turbo Pascal 3.0. :)