DevCity.NET - http://devcity.net
Product Review: ComponentOne's DocToHelp
http://devcity.net/Articles/249/1/article.aspx
Scott Waletzko

Scott Waletzko has been an Information Technology professional and Windows / Web programmer since 1995, with experience in software development and architecture, network design and administration, and project and team management. Currently he is the the Senior Vice President of Technology at Intellisponse, as well as the President of Skystone Software / Echosoft Design Studios, LLC.

At Intellisponse, Scott is responsible for architecture and implementation of the company flagship software called Synapse, the first full-featured Web survey authoring tool for market research, enabling researchers to design, publish, and manage full-featured and logically complex questionnaires to the Internet without programmer interaction.

As president of Skystone Software / Echosoft Design Studios, LLC, Scott is developing a unique Web site content management system named Tempest, which will drive myBard.com and provide comprehensive Web site hosting and content management to anyone with a Web browser.

 
by Scott Waletzko
Published on 7/14/2006
 
A review of ComponentOne's DocToHelp help file authoring and conversion software, written by Scott Waletzko.

DocToHelp Overview

Overview
ComponentOne's DocToHelp help file authoring software enables developers to author help files and documentation for their projects in a variety of standard help file formats. Users can choose to start a new documentation project from scratch, import Xml documentation files (as generated by Visual Studio), or convert from a variety of other help file authoring formats to form the basis for the documentation. Once a project is created, topics can be added, edited, and removed through the main user interface.

Project Converters
DocToHelp provides the ability to convert a variety of existing help documentation source file types, including the following:

  • RoboHelp(R) HTML
  • RoboHelp(R) Word
  • HTML Help
  • WinHelp
  • Doc-To-Help 2000

Output Types
A wide variety of output documents are supported, including:

  • Microsoft Help 2.0 (Similar to that used by the MSDN collection)
  • HTML Help (The standard desktop online help format, replacing WinHelp)
  • JavaHelp  (Sun Microsystem's help format)
  • Printed Manual
  • NetHelp (HTML-based documentation for browser viewing)
  • WinHelp (Microsoft's pre-HTML help format)
 

Features

Source Files

DocToHelp uses Word and / or HTML files to be used as the source documents for a project. Word documents can be edited within the DocToHelp interface or externally in Word. HTML documents are edited in the HTML editor of your choice (mine defaulted to Visual Studio), but the software is geared specifically for use with either Microsoft FrontPage or Macromedia Dreamweaver.

The idea behind DocToHelp is that the help file authoring itself is done in source Word or HTML files, rather than in outline form. Predefined DocToHelp styles applied to the elements in the source files defines that element as a type of help file element, and are used by the target compiler to format the output files as well as to build the table of contents and indexes for the help files.

Once built, the table of contents and index can be used to navigate and filter the source document(s), providing a quick way to edit specific elements in the source document(s):

A Word toolbar is provided that includes a handful of default DocToHelp style shortcut buttons as well as an image map editor, and appears whether the document is being edited within the DocToHelp UI or in Word. There is a similar toolbar included for editing HTML documents in Microsoft FrontPage and Macromedia DreamWeaver, but not Visual Studio, which means that if you use any editor other than those three (Word, FrontPage, DreamWeaver) you must apply the element styles manually.

Advanced formatting options include links, jumps, pop-ups, cross-references, dynamic text (expanding, drop-down, and conditional), and the ability to edit context ID strings for context-sensitive help support.

Documenter For .NET

One of the strongest features of DocToHelp is the Documenter for .NET, which supports creation of a documentation project file based on a compiled assembly and (optionally) the documentation Xml files generated for the assembly by Visual Studio. An external component that is launched from the File menu in DocToHelp, this component allows the user to select one or more .NET assemblies from which class documentation will be automatically generated.

Once the assemblies are selected, clicking "Generate New Document" creates a new source Word document containing complete documentation for the selected assemblies (using a combination of Reflection and an Xml comments file if supplied).

The result is a class library documentation file similar to the .NET Framework documentation files:

 

Summary

Product Quirks

I'll be the first to admit - I am not a patient person by default. DocToHelp, however, continually tried my patience as I used it, severely reducing my perception of its overall usability. I tested the software on a laptop with an Intel 1.73 GHZ Pentium-M and 2 GB of RAM (my development machine) and despite this computing power it had an annoying habit of continually locking up as I interacted with the user interface. This behavior was so prevalent that it got to the point where I would click something in the user interface and then go browse the Web while I waited for the software to catch up. Worse than blocking itself, however, any intesive process (like building output files or converting assemblies in the Documenter for .NET) would slow my entire computer down to the point where it would take over a minute for me to open a new browser window.

My guess is that the speed issue has to do with the fact that the source documents for help files are Word or HTML documents, and therefore have to be parsed each time a new request is made. Summary
DocToHelp by ComponentOne is an ambitious product, attempting to provide a one-stop solution for any help file authoring needs, which it accomplishes to a certain extent. The conversion types, Documenter for .NET functionality, and comprehensive output options provide a wide range of features that facilitate creation of rich and consistent documentation for software.

Pros
Documenter for .NET provides a quick and easy way to create help documentation for a development library simply by choosing the assemblies to include in the documentation and then choosing an output type. This feature alone makes the document invaluable to .NET developers who wish to document their class libraries (assuming that the proper attributes were added to the source code in order to generate a comprehensive Xml comment file for each assembly).

The product is highly customizable in that custom document templates or style sheets can be used to create default source documents, and the compile behavior of individual styles can be modified using VB Script. This means that the longer a user works with the product, the more it will learn to suit their needs.

Personal Preference
Not having used any previous versions of ComponentOne's help file authoring software (or even a competitive document-based authoring system), I found the learning curve associated with manipulating the source files to be a bit high, especially if you prefer to work with HTML source files and do not use FrontPage or DreamWeaver. My personal preference (and this is purely subjective) would be to work in an outline format. DocToHelp attempts to supply this with its table of contents and index views, but ultimately no matter how you approach the source document you are still editing it in either Word or an HTML editor. To be fair, anyone who has already become comfortable using a document-based help authoring system will likely feel more at home than I did with the DocToHelp interface, and the styles included are intuitively named, for the most part.

Cons
Whether you love or hate the document-based (as opposed to outline-based) authoring approach, there is no getting around the problems with responsiveness in the user interface of this product. During the course of my evaluations I created two different documentation projects: one based on a simple class library assembly, the other based on a complex class library project made up of 8 different assemblies. The smaller project was unresponsive enough to cause frustration pretty much every step of the way (including throughout the Documenter for .NET import process), and the larger project was virtually unusable because of the amount of time it took for each interface request to be responded to by the program.

Compile times for each project were quite long (depending on the output type), but that is for the most part understandable, and since compiling the output is not done until the end of a project, is also not a huge problem. Having to wait for the interface to respond as I tried to edit the document and otherwise navigate through the user interface, however, was unforgivable.

Verdict
The multitude of output options makes this an attractive solution for software documentation requirements. With DocToHelp, a multitude of output types (online help, Web help, and printed manual) can all be generated from a single source file. The Documenter for .NET automates manual documentation of code libraries and is therefore invaluable to developers. Despite DocToHelp's frustrating usability issues, I am sure that I will be using this product again in the future simply because it is so versatile and has so many options.

If you are in the market for a help authoring tool, the well-roundedness of this product makes it a strong contender, but I would suggest demoing both this and competitive products before making a purchase to be sure that if DocToHelp is your final selection you can get past the quirks in order to benefit from the variety of features.

DocToHelp | Manufacturer: ComponentOne | Feature List | Price List