I'm not usually posting product plugs in this BLOG but in light of the beta release of Html Help Builder today I thought I 'd share some notes on how I use the new Visual Studio .NET integration features of Help Builder. When I originally set out to add these features I was really ho-hum about what value they would provide. But now that they're in Help Builder I'm really stoked that they are there - they are making my life a lot easier while giving me much more opportunities to document my code as I go.

So, I finally got around to posting a beta version of HTML Help Builder today after a lot of putting it off at the last minute due to fixing a number of small issues. But what really took time and is somewhat ironic is that I really needed to do some work on the HB documentation - imagine that! The docs for Help Builder are pretty weak (they still are but I'm working on it <g>), and at this point somewhat out of date since the product has changed so much. Writing Help Documentation isn't too bad, but updating existing documentation is. Aarrgh.

All that said, I'm pretty excited about this release of Help Builder which includes Visual Studio .NET integration via an Add-In. I've been working simultaneously on an update to the West Wind West Wind Web Store .NET application and using the new features has come in really, really handy. The way I work I usually import my classes into Help Builder using the Import Wizard to pull in the class(es) from the Assembly and XML documentation if available which provides very rich information about .NET types. This usually gives a great starting point. But I tend to write lots of documentation and add examples and notes to topics which becomes a little much to do in the source code. So I end up working mainly inside of Help Builder for finalizing the documentation. The problem in the past with this has been that there was no way to easily reimport new or updated data that lives in the source code. Although you can re-import it's either overwrite everything, or import only into fields that were previously empty, neither of which work great if you modify the imported original data.

Well, now Help Builder CAN import individual methods, properties, fields, events and class headers directly from the source file at least for C# code (VB doesn't support XML comments natively so there's no useful informaiton there by default - but you can still pull in signatures). This makes it a snap to immediately import a new method or property into Help Builder right from the source code. Right  click and Update Help Builder from C# Code and a new Topic (or an Update) dialog pops up that lets you figure out where to stick the new topic. For me this has been a huge time saver as I'm working on a new version of the West Wind Web Store and there have been a number of additions. This works handily even if I go in now to look at changes I've made over the months and neglected to document.

There have also been a number of enhancements in how Help Builder imports .NET classes and members. Help Builder now pulls a signature for each member imported based on the namespace.class.member and for methods method parameters. This ID makes it much easier for Help Builder to perform multiple imports. It also what makes it possible to let the Add-In figure out if a member to update already exists or whether to create a new one. It's still not fail safe because if you change a method's signature the signature link with Help Builder will go out of sync and it will treat the new method like an overload, but hopefully this is something you can easily catch once a method has been imported. In addition you can now view and edit the signature of class members so if you change a method you can keep it in sync by changing the signature, then using the Add-In to pull in the updated signature and docs.

Unfortunately for me, older versions of Help Builder didn't use signatures, so a lot of the West Wind Web Store documentation actually doesn't use signatures, so synching up from source code is a little more of a manual process. There's another trick I use for these imports: I open another instance of Help Builder and load a test project. Then I import the class in the test project. I find any members missing in the main project and simply drag and drop them into the main project.

Help Builder also generates C# XML comments from topics, so for all but the really lengthy topics I've gotten into the habit of back documenting the source code from the Help Builder topics too. This is so easy - simply put the cursor anywhere inside of a class member right click and select insert C# XML comment and voila the current Help Builder topic is now adorning the method in XML Comment format.

As part of the West Wind Web Store I also finally got around to documenting the West Wind Web Store Offline Application by creating a runtime Help file for the application. This is actually the Help Builder VS.NET Add-In shines the most. I can simply drop a Help Provider (actually I use a custom Help Provider - more on that in a second) onto a form, which enables Help Builder integration for this form so that I can directly pull HelpString values from the currently selected Help Builder Topic. Again this makes hooking up Help files so much easier, especially if you're not quite as lazy as me and you actually create context sensisitive help for controls on a form rather than just documenting forms or major containers (Tab Pages mainly) on a form. <g>

But the real winner here is use of the HelpBuilderHelpProvider which lets me hook up HelpStrings to topics and go on during development. Then when I run the application I can press Alt-F1 (customizable) to pop up Help Builder and document the application at runtime. As long as the HelpString values are hooked up and match Help Builder topics I can now document my application at runtime in a context sensitive manner. Believe me this is a big timesaver in anything but a trivial application. Of course this feature is also awesome if you pass your documentation creation tasks off to technical writers or other non-programmers which is common for end-user applications.