Review of ComponentOne's Doc-To-Help 6.0
By Matthew Ellison
Contents
Click a link below to jump to a particular section; click any "TOP" image following a section heading to jump back here.
Introduction 
Doc-To-Help was one of the first authoring tools for Windows Help having been around since 1991. As the name suggests, early versions of Doc-To-Help were based on the principle of creating a printable document within Microsoft Word (using certain styling and layout conventions imposed by Doc-To-Help), and then converting that document into an online Help file. The work flow implied a primary target of paper documentation with the authoring environment oriented to showing the information in that form.
The latest version of the product, Doc-To-Help 6.0, is somewhat different. The authoring process has changed to that of developing content (albeit still within Microsoft Word), and then generating that content into a range of possible target formats. Print is now just one of these targets—the others comprise a comprehensive range of online Help formats, including WinHelp, HTML Help, and JavaHelp. This is an important change effectively disengaging the product from print as the primary metaphor, and places the product in the domain of single-sourcing tools that do not favor any specific output medium.
The reason for the change is the acquisition of Doc-To-Help from WexTech Systems by ComponentOne, who have totally re-engineered the product and combined it with some of the technology of its own existing Help tool, True Help 1.0. The new Doc-To-Help is effectively a combination of the old Doc-To-Help and True Help, with the some of the best features of each evident in the resulting product. The disadvantage is that the dual ancestry makes for a fairly complex interface.
This review describes my personal impressions of ComponentOne's Doc-To-Help 6.0 after familiarizing myself with the product. My previous experience with Doc-To-Help had been limited to brief experimentation with versions 4 and 2000. I had never used either version for a real-life Help project, and I was effectively approaching this new product as a novice.
Overview of Doc-To-Help 6.0
As I mentioned in the introduction, Doc-To-Help 6 is based on two previous products: Doc-To-Help 2000 and True Help 1.0, both requiring Microsoft Word for creating and editing content. The strength of Doc-To-Help 2000 was its use as a tool for single-sourcing print documentation and online Help. An author had to use certain conventions for laying out and formatting the document, and it was not a straightforward process to convert existing regular Word documents to online Help. True Help 1.0, on the other hand, imposes fewer proprietary conventions and enables you to convert regular Word documents to online Help very easily. However, it offers a far less rich set of print formatting features than Doc-To-Help 2000.
Doc-To-Help 6.0 combines the strengths of these two previous tools very effectively. The content is written as one or more continuous documents, with separate topics identified using paragraph styles. For example, the heading styles (Heading 1, Heading 2, etc.) are typically used to indicate the start of a new topic. However, it now stores information about each of the topics in your project within its own database. The authoring tool, therefore, consists of two distinct UI elements: Microsoft Word, which most of us are already familiar with, and the Doc-To-Help "Project Editor," a multi-paned application window that enables you to edit the project database.
It strikes me that the product could be used in either of the following ways:
- To generate online Help from a regular Word document source
- As a sophisticated authoring environment for single-sourcing a range of online and paper-based formats
In the first scenario, the source content could be maintained independently of Doc-To-Help by authors who would require only certain basic Word skills (in particular, the ability to use paragraph styles, insert index markers, and insert cross-references using Word's cross reference field). The more structure, styling, and meta information that have been built into the Word document, the better job Doc-To-Help will do of creating a full-featured Help file. One person with Doc-To-Help expertise could be assigned to set up the project, and then to generate the required output formats at the appropriate times.
In the second scenario, the content author would work with both parts of the Doc-To-Help UI, switching back and forth between Word and the Project Editor. To take advantage of the full range of features (including conditional text, popups, ALinks, windowing, etc.), authors would need to have a good knowledge of Doc-To-Help.
Installing Doc-To-Help 6.0
When I opened the box I was rather pleased not to have to dig through a sheaf of marketing literature to locate the CD. The contents comprised four items: a CD, printed license agreement (one sheet), registration card, and a 280-page manual (which didn't look too intimidating).
The installation program was built using Wise, and ran in a browser window. Because of this, it felt like I was installing a program from the Internet (which was not the case). At one point a File Download dialog appeared informing me that I was downloading the file C1D2HSETUP.EXE from F:\, and inviting me either to Open it or Save it. The correct action is to open it (to run the setup program), but I can imagine some users being confused by these options and making the wrong choice. After negotiating that and entering my serial number, the installation process was extremely smooth and rapid—I was not required to reboot my PC.
The Familiarization Process
First Impression
After starting the application, I was confronted with the Doc-To-Help Project Editor as shown below (more on this editor later in the review).
I was hoping that I might be able to improvise my way through creating a simple project based on my experience of using other Help Authoring Tools (including RoboHelp, ForeHelp, and HDK), and to a certain extent I was able to do this. However, my progress was fairly slow and uncertain, and I continually had the impression that I might not be going about things in the most efficient way. I also found that there was a whole host of features within the interface that I did not understand and was not able to make use of—time to turn to the manual and the online Help!
The User Manual
The manual started with a section listing the features that would be new to previous users of Doc-To-Help 2000 and of True Help 1.0. This included useful references to more detailed coverage of each new feature later in the book.
The second chapter of the manual introduced the basics of Help authoring, which I expected that I would be already familiar with. However, I was rather confused by the explanation of the differences between compiling, making targets, and rebuilding targets, and I found this information too conceptual for this early stage of my learning process. Upon reaching the end of the chapter, my conclusion was that the manual was probably too advanced to be of benefit to newcomers to online Help.
The next chapter contained a detailed description of the Doc-To-Help Project Editor, and provided far more detail than I felt ready to assimilate. I moved quickly on to the following chapter, "A Guided Tour of Doc-To-Help" and worked through it step-by-step. This was the information I needed! It led me through the entire process of setting up and working with a project, and by the end of it I felt that I had a reasonable overall grasp of the tool. My only quibble here would be that one of the early tasks (Using the Organizer to Copy a Style) seemed unnecessarily complex and intimidating, and could have undermined the confidence of some new users.
The remainder of the book contained more detailed conceptual and task-based information on all the main features of Doc-To-Help, and an Object Model Reference. This very technical-looking section (it's laid out like a programmer's guide) is an exhaustive listing of the properties that can be assigned to the various elements (styles, topics, documents, etc.) within a project.
Online Help
On examination, it turns out that the online Help for Doc-To-Help 6.0 is a straight replication of the content of the manual (as shown below). This is a clear demonstration of the single-sourcing capabilities of the tool, but it might have made sense to have made some judicial use of conditional text to prune down each of the two output formats.
For example, working through the paper-based "Guided Tour" was very easy for me—I could lay the book on the desk in front of me, and read the instructions as I worked with the sample project on screen. This would have been much more difficult to do switching back and forth between the application and the online version of the "Guided Tour" (maybe if I had a bigger monitor screen…).
On the other hand, I can't imagine anyone choosing to use the paper-based version of the Object Model Reference, especially as the online version of these topics is embedded right into a pane within the Project Editor. This means that when you select a property in the editor, its description is displayed automatically within the Help pane—a very neat feature!
Key Components of Doc-To-Help 6.0
The Doc-To-Help Toolbar
When you install Doc-To-Help on your PC, an additional toolbar (shown below) becomes available within Microsoft Word. This provides useful shortcuts for some standard Word operations (such as applying heading styles or inserting standard cross-references), as well as providing access to some special Doc-To-Help functions (such as adding dynamic links or building the current Help target). This small toolbar is very effective in making most of the common operations quick and easy, and I particularly appreciated the range of buttons available for defining different types of list items.
I would have liked an additional button for assigning the Heading 5 style (the style that Doc-To-Help reserves for glossary terms)—assigning a paragraph style using Word's conventional method is less straightforward than usual because of the very long list of predefined styles you have to select from. ComponentOne has told me that the next patch release (due either this month or June) will contain a command for adding glossary terms.
If you don't want to see the Doc-To-Help toolbar when you work on your regular documents in Word, you currently have to switch this toolbar on and off manually as you switch between Doc-To-Help documents and regular Word documents. According to ComponentOne, the next patch release will make this unnecessary.
The Project Editor
The Project Editor is the application that enables you to display and edit the contents of Doc-to-Help's project database. It has a complex user interface consisting of five different "views" of your project, each accessible from an icon bar on the left-hand side. In that respect, it's somewhat reminiscent of Microsoft Outlook.
Each of these views has its own selectable tree list of items—as you select each item, the detail of that item is displayed within up to three panes on the right. As an example, the following screenshot shows what you would see if you had selected the Project view, and then the Paragraph Styles item, followed by the Heading 2 style, and the Nonscrolling property for that style (which you can set to True or False). The information within the lower right pane is the embedded Help for this particular Property.
Once you master it, it's a structured layout that obeys all the rules of logic. However, as a novice, I certainly found it a little daunting.
Doc-To-Help enables you to assign specific properties to a range of different items and objects within your project. So, you can specify that each occurrence of a specific paragraph style within Word represents the start of a particular type of topic, and then you can assign properties to that topic type. For example, you can specify that the paragraph style should link automatically to its child topics, that it should appear in a specific window, and/or that it should be automatically indexed with its topic title. Even though the power of Doc-To-Help is realized by categorizing topics in this way, you also have the option to change the properties of individual topics, thus over-riding the properties inherited from those defined for the paragraph style.
You can take this flexibility as far as you'd like. Or, you can do as most Doc-To-Help users will (I suspect) and simply define a relatively small number of paragraph styles and topic types, and let Doc-To-Help do the rest.
The Topic List
In the Topics "view," Doc-To-Help presents you with a variety of different lists of topics within your project. The list that I used most was the one containing all the topics in my project. However, it's also possible to focus the list on only those topics that have had specific items (such as keywords) assigned to them. More useful than this, perhaps, is the ability to list the topics that have not yet had these items assigned to them. This enables you easily to display and work with all the topics to which you have not yet assigned keywords or context IDs, for example.
Each of these lists can be further customized: You can sort the topics by either title, the Word document in which they are stored, or the Word paragraph style that is used for the topic title. This sorting mechanism takes a little getting used to. Instead of simply clicking on the column heading to sort by that heading, you actually have to drag the column heading into the dark gray space above the topic list.
In addition to sorting, you can filter the list by typing the initial letters of the topic title, selecting a specific document, or selecting a specific paragraph style. In this way, you can easily "home in" on the specific topics that you want to work with, even in a very large project.
The example below shows the topic list sorted by style name, and then by title, with a filter applied so that only the topics held in StyleGuide.doc are displayed.
This sorting and filtering capability is available whenever a list of topics is presented to you within the Project Editor, for example, in the Contents view that enables you to drag topics from the list into the table of contents.
Using Doc-To-Help 6.0
Creating Content
Since Doc-To-Help uses Microsoft Word as its topic editor, creating content is basically a matter of typing text, creating tables, and inserting pictures in the same way as you would for a regular Word document. You have the benefit of using a familiar authoring environment, and you can take advantage of some of Word's advanced productivity features, such as macros.
The disadvantage is that the Word editing environment was not designed specifically for Help authoring. As a result, a number of features built into Word are totally redundant within the Doc-To-Help environment. Also, you do not have built-in authoring support for some of the more advanced features of a Help system, such as DHTML expanding text and drop-downs. You can achieve these effects, but only by typing the required HTML code into your document, and then using the Doc-To-Help toolbar to mark it up as "HTML passthrough code". This is something that many Help authors would not feel comfortable doing.
Applying Formatting and Styles
Each of your Help targets (that is, the output formats that you generate from your project) has a corresponding Word document template. This document template must contain a set of paragraph and character styles whose names match the styles that you are working with in your source Word document. These style definitions within each Word document template determine the text formatting within the corresponding Help target. So for example, what Doc-To-Help actually does when you generate an HTML-based target is to create a Cascading Style Sheet (CSS file) based on the styles within the appropriate Word document template.
The advantage of this approach is that you don't need to know anything about CSS, and can instead use Word's familiar style-editing features for creating the desired formats with the document template. The downside for more savvy authors is that Doc-To-Help does not write HTML and CSS in the way that you would necessarily choose to do if you had full control. For example, it marks up all paragraphs (including headings) using the <P> tag, and differentiates between the original Word paragraph styles using Classes. This conflicts with accessibility guidelines from the Word Wide Web Consortium (W3C), and means that the resulting HTML lacks the heading tags (H1, H2, etc.) that some specialist browsers rely on to recognize page structure.
For example, this topic extract:
has the following underlying HTML code:
Creating Links
Many different ways are available to create hyperlinks between topics, using either Microsoft Word or the Project Editor. Adding a topic link within Word is not as easy as it might be, because there is no way to insert the link text automatically. This is not a problem if you are adding an inline link within a paragraph that you have already typed, but it is a little annoying if you are creating the link from scratch.
Doc-To-Help will convert cross references (inserted using Word's cross-reference field) into hyperlinks. However, you can also insert hyperlinks using special character styles. It will even automatically insert hyperlinks based on the relationship between topics. For example, it will insert links from a topic to all its subtopics (the topics that are immediately below it in the table of contents hierarchy).
Finally, Doc-To-Help enables you to highlight a piece of existing text and use the "Add Topic Link" button on the Doc-To-Help toolbar enabling you then to choose from a list of topics within the project (which you can filter and sort to your own requirements):
This method for creating links is a very convenient way of creating inline hyperlinks that operate in all the online Help outputs, but do not show up in the print version.
Creating a Table of Contents
By default, Doc-To-Help creates a table of contents for a Help project automatically, based on the sequence and heading hierarchy of topics within the source Word documents. However, you can override this default structure by editing the table of contents within the Doc-To-Help project window. This enables you, for example, to permanently remove specific topics so that they are still a part of the project, but not listed in the table of contents. You have to keep in mind that, having edited the table of contents by hand, new topics are not subsequently added to the table of contents automatically.
Creating an Index
Doc-To-Help uses the index entries inserted through Word's own indexing function. However, you can supplement these by entering new keywords within the Project Editor—Doc-To-Help stores these keywords within a database (not within the Word document).
One of the most powerful features of Doc-To-Help is the ability to analyze the content of each topic and automatically generate suitable keywords through scripts. Note that this feature is not a simple point-and-click interface, and does require VBScript expertise. As an example of how you might use it, you could develop a script that would process a set of topics titles of the form "Adjective Noun" and automatically assign the following keywords to each topic:
adjective noun
nouns
nouns, adjective
You can also use scripts in a more restricted way to modify the automatic keywords assigned by Doc-To-Help, for example, to change them to lower case.
Using Conditional Content
Conditional content is one of the hallmarks of a true single-sourcing tool. Doc-To-Help enables you to build different outputs, customized for specific formats or purposes, from the same source project.
Doc-To-Help supports conditional text, but, rather surprisingly, does not enable you to flag entire topics within its database as being conditional. To mark text as being conditional, you highlight the text within Word and click the "Apply Conditional Text" button on the Doc-To-Help toolbar. The following dialog then appears, and you have to choose between making the text conditional to a specific platform, Help target, or attribute.
Attributes enable you to create conditional text based on your own criteria. For example, the two attributes above enable you to mark text as being specific to an internal build or to a release build of the Help. You can add your own attributes within the Project Editor.
Generating Help Targets (producing online or paper-based output)
A "Help target" is the term that Doc-To-Help uses for a specific output format. The following Help targets are available:
- HTML Help 1.3
- WinHelp 4
- Plain HTML
- JavaHelp
- Word (printed documentation)
You can create your own custom Help targets (which might include certain configurations of conditional topics) but these would be based on one of the standard formats listed above. According to the documentation, you are able to create a Help target for Microsoft Help 2. However, you need to have Microsoft's Help 2 compiler installed in order to do that, and Microsoft has postponed its general release of the Help 2 compiler until at least 2003.
Help target (output format) generation occurs in two distinct stages. First, you have to "Compile" each of your source Word documents. This stage involves Doc-to-Help analyzing the styles within the document and creating a RTF version of each document using its own special markup. During the compile stage, it also creates the appropriate output format for each of the topics—so for HTML-based formats, it creates a set of .HTM files.
Following that, you "Make the Target"—this is the process of creating any additional files required for the output (style sheet, table of contents file, index file, project file, etc.), and then (in the case of HTML Help and WinHelp) using the appropriate compiler to produce the final compiled file.
You initiate the entire process with a single button-click, but it can take quite a long time to complete (several minutes for a large project). However, it's much quicker than it was in previous versions of Doc-To-Help, because the processing is done using compiled code outside of Microsoft Word, whereas the compilation and build process in previous versions of Doc-To-Help was executed within the Word environment using Visual Basic. Another reason for the increased speed is an "incremental build" facility, which means that only the source documents that have changed since the last build are compiled—previous versions of Doc-To-Help always processed every file in a project.
Summary
During my familiarization process, I found that I had a lot of new concepts and terms to get to grips with (not least of which was the subtle but important distinction between Building, Compiling, Making a Target, and Rebuilding a Target) and a somewhat daunting interface to find my way around. However, my impression from the outset was that there was considerable power and flexibility lurking within the product.
My view of the key strengths and weaknesses are as follows:
Key Strengths
- The ability to create a variety of online Help formats from a standard Word document with minimal post-processing
- Access to the powerful word-processing features built into Microsoft Word
- Conditional text that enables customized versions of the Help
- Powerful and flexible indexing capabilities
- Useful automated linking based on the topic hierarchy
Key Weaknesses
- A complex and somewhat quirky user interface
- Relatively new and untried underlying code
- Lack of support for conditional topics
- Lack of built-in support for DHTML effects, such as expanding text and drop-downs
- Restricted functionality of the plain HTML output format (which may be remedied by the InterHelp technology acquired from ForeFront, which ComponentOne plans to incorporate into a future version)
For more information about Doc-To-Help 6.0 visit the ComponentOne web site.
| 
