Product:
ComponentOne Doc-To-Help 7.2 Professional
Company:
ComponentOne, www.componentone.com
Price:
$999.95
Platform:
Windows 98, ME, 2000, XP with Microsoft Word 2000 (version 9.0) or later and .NET Framework version 1.1

ComponentOne's Doc-To-Help 7.2 Professional is a Microsoft Word-based help authoring tool that generates help files in multiple formats. What makes this tool especially relevant to .NET developers is its new .NET Documenter feature, which creates MSDN-style documentation from compiled assemblies and XML comment files.

Here's how the process works. To create a help file with Doc-To-Help, you open the Doc-To-Help project editor and select New from the File menu. The New Project wizard walks you through creating the project file and selecting some options before it generates a Word document and drops you into Microsoft Word.

Doc-To-Help is integrated pretty tightly with Word. It adds items to the Word menus (thankfully at the bottom of the menus rather than in-between normal Word menu items), and includes a toolbar with quick links to often-used features. It took a couple of hours to get comfortable with creating and formatting help topics, but it soon became almost second nature.

From then on, most of the process of creating a help file is writing and editing in Word. It really is that simple.

After you've created a few topics, you'll want to generate the help file to see how it looks. Switching back to the project editor, you can quickly compile your help file into one of several different formats (HTML, Microsoft HTML Help, JavaHelp, WinHelp, MS Help 2.0, and Printed Manual) and launch the help viewer from within the project editor.

The whole process initially sounds mystifying, if you've never created a help file, but the software's great documentation and online help will help you over any rough spots.

I will caution you that you absolutely do not want to have other Word documents open while you're working in Doc-To-Help. Word gets very confused when other document windows are open, and I had to use Task Manager to shut down the program a couple of times while writing this review. It could be that these problems are due to old software versions. I'm running Word 2000 (version 9.0) on Windows 2000 Professional—a configuration I've had for the last five years. Perhaps things work better with Windows XP and the latest version of Word.

The few problems I've experienced aren't unique to Doc-To-Help. I've run into similar problems with RoboHelp and other Word-based help authoring tools over the years.

The New Stuff: .NET Documenter

The .NET Documenter is a new feature in Doc-To-Help version 7.2. It reads compiled assemblies and XML comment files to create a Doc-To-Help project that contains MSDN-format class documentation for the classes in the referenced assemblies. This goes much further than the documentation generation tools that come with the .NET Framework.

To test the Documenter, I pointed it at a class library I've been developing, and told it to generate class documentation. It took a little over a minute for Documenter to process the assembly and the XML comments and create the Doc-To-Help project. Once that was done, it took one more step to generate a compiled HTML Help file. The result was quite impressive: every class and class member was identified and presented in the same format as the .NET documentation, including "Overview" and "Members" pages for each class, object hierarchies, and "See Also" links. The few XML comments that I had included in the class were faithfully copied to the proper places in the generated document.

Like any other automated documentation tool, the Documenter only adds the information that it can get from the assembly (class name and member information) and from the XML comments file. You still have to add detailed discussion and examples manually. This poses something of a problem with the .NET documentation tools; they have the tendency to overwrite their output files, erasing any changes you've made. The Documenter gets around that by using different text styles for generated text than for text that you create. As long as you don't change any of the automatically generated text, Documenter will preserve the changes that you've made when it regenerates the documentation.

There's even a sort of manual version control system build in that will let you save older versions of your help project and regenerate topics for those versions. You just have to remember to click the backup button before generating a new version.

Help Doc for the Help Doc

The printed manual that comes in the package is a very complete introduction to help systems in general. It's presented in terms of Doc-To-Help, of course, but educational nonetheless. The manual includes a guided tour that walks you through creating and compiling your first help file, and is followed by chapters that give step-by-step instructions for creating help projects, using styles, organizing topics, creating links and indexes, and customizing help windows.

It's rare these days to see a printed manual included with a software product. It's especially rare to see one that's this complete and written this well. It appears that the only things missing from the printed manual are the new features and corrections in version 7.2.

If you want to view the product documentation online, you can. The complete manual is available in a PDF file on the distribution CD. This file includes documentation of the new version 7.2 features.

Doc-To-Help is a first-rate help authoring tool that I would recommend to anybody who needs to create online help for their product. Its tight Word integration, automated generation, and excellent documentation rank it right up with other top-of-the-line tools. The addition of the .NET Documenter makes this tool a must-have for any development team that wants complete and well-formatted documentation for their class libraries. If you're in the market for a help authoring tool, Doc-To-Help 7.2 Professional is certainly worth looking into.