Indexing with Doc-To-Help. Boulder Writers Alliance, Boulder/Denver, Colorado.


	Indexing with Doc-To-Help	Search BWA Web Pages

By: Lori Lathrop
July 1996

I am a technical writer who has worked with a variety of word-processing packages and desktop publishing (DTP) software to develop both printed and online computer documentation. Also, as a freelance indexer, I often use CINDEX.

Few indexers are proficient in using DTP software, such as FrameMaker, which technical writers use for large documentation projects and writing online help for software products. Likewise, most technical writers have never used indexing software such as CINDEX or Macrex. However, many technical writers have learned about these tools for the first time as participants in my Index Evaluation Workshop and my two-day Indexing Skills Workshop for Technical Communicators.

Most DTP programs allow writers to create indexes by embedding index "tags" in the document itself. These tags, which are like programming code, tell the DTP program how to generate the index when the writer formats and prints the document.

Of course, both embedded indexing techniques and stand-alone indexing tools have their advantages and disadvantages. This article will not say that one method or the other is the best way. The fact is that, if you're a good indexer, you can create quality indexes with whatever tools you have.

Doc-To-Help, developed by WexTech Systems (310 Madison Avenue, Suite 905, New York, NY 10017 / 800-WEX-TECH), is a popular tool for creating printed manuals and online help from a single source, complete with a table of contents and an index. It is an add-on product for Microsoft Word, and it requires Windows 3.1 and at least 2MB of memory installed on your computer (4MB recommended). I am not endorsing Doc-To-Help or denouncing it. Rather, my goal is simply to examine the indexing capabilities of Doc-To-Help.

Some advantages of Doc-To-Help

I first heard of Doc-To-Help from another technical writer who said that, for him, the program makes indexing an easy task. He likes being able to designate index targets (words or phrases in the document) and generate tags (code that builds the index entries from targeted words and phrases). After the writer specifies all the target codes in the document, Doc-To-Help inserts embedded tags that match the specified words or phrases, along with locators (page references). One advantage, according to my writer friend, is that he can easily change the index by removing all the target codes and specifying new targets.

Doc-To-Help saves all of the index targets and associated tags in an ".INI" file, which the writer can edit from within Doc-To-Help. Writers can also use another word processing or editing program to perform these edits; however, editing within Doc-To-Help is preferable.

My first reaction was skeptical. Sure, I thought, it sounds handy, having the software automatically build an index for all the words associated with specified targets, but ... I had a lot of questions, such as:

How do you prevent it from including index tags for passing references? For example, there may be some meaningful index entries for "syntax" but, at the same time, the word "syntax" may be insignificant in some parts of the text.
Can you edit and easily delete the unnecessary tags? And, if so, is it still worthwhile to generate automatic index tags?
Also, how do you handle index entries for concepts (when the exact words may not be in the text)?

Who was it who said, "Indexes are written, not generated!"

And some pitfalls

As I expected, there are a few pitfalls in using a tool like Doc-To-Help. My friend confessed that he had created an index list of about 200 targets (words) the first time he used Doc-To-Help. And (get this!) one of the words in his list was "AND." Actually, he had a good reason for doing that. You see, he was writing a manual for an electronic diagramming program, and, in addition to being a conjunction, "AND" is a term used to describe connections between electronic components.

By now, I'm sure you've guessed what happened. Doc-To-Help inserted targets at every instance of the word "AND" ~ and it caused his computer, a 486 PC with 4MB RAM, to crash! The word "and" occurred over 1,000 times in the document. Can't you just imagine it as an index entry with more than 1,000 page references?

Using the Discretionary Index option

To fix the problem, the writer redefined the index list and, this time, he used Doc-To-Help's Discretionary Index option. Here's how it works:

After completing a list of index targets, select Indexing from the Tools menu.
When the Indexing dialog box displays the list of index targets you specified, double-click any target for which you want discretionary indexing.
When the Options dialog box appears, select Auto if you want to insert tags for all targets or, better yet, select Discretionary if you want Doc-To-Help to prompt you at each instance. (Auto is the default.) Let's assume that you selected the Discretionary option.
Select Search Criteria, then select one of the following:

Match Upper/Lower Case
Match Whole Word Only

Next, select Placement Position, then select one of the following:

First Instance after a Heading
First Instance on a Page
First Instance in a Chapter
Every Instance

After setting the target list options, which Doc-To-Help puts in an .INI file, you can tell Doc-To-Help to insert the targets by selecting Build Index from the Indexing dialog box. If you select Discretionary Indexing for a word, Doc-To-Help will prompt you at each instance of that word. It will open the document at each location and then display another dialog box with these options:

Insert Custom Tags
Skip This Location
Extend from Previous Index Tag
Move to Next Target in List
Finalize Discretionary Indexing
Exit Indexing Program

If you delete index targets or tags (or if you edit MS Word tags), you must rebuild the index. To do this, you would select Repair Manual from the menu, then tell Doc-To-Help to remove all existing index targets. This takes about five minutes for a document with 200 targets. After you select Tools-Indexing- Build Index, Doc-To-Help inserts the revised list of new targets throughout the document at selected positions. This takes about an hour on a 486 with 4MB RAM and 33MHz. At the end of this build process, Doc-To-Help creates the actual index (comprising tags and page numbers linked to targets) at the back of the document. This takes about one minute.

Indexing concepts

Now, what about creating index tags for concepts, when the exact words may not appear in the text? The good news is that Doc-To-Help is flexible enough to do that. Here's how:

You can create as many index tags as you like for a target. You can give these tags any name ~ specific or general, related or unrelated to the target. In this way, you can create a tag for a concept, such as "creating online help" or "generating reports" ~ associated with any target. Doc-To-Help inserts all the tags at target locations, and those tags (along with page numbers) appear in the index when you build it.

For instance, if you designate "report" as a target, you can create any of the following tags: "reports", "printing reports", "output", or "generating hard copies".

Also, Doc-To-Help lets you create different levels (subheadings) by separating tag words with a colon. Examples: "connecting gates:AND", "connecting gates:OR", "connecting gates:IF, "output:reports", "output:monitor", "output:plotter". The formatted index will look like this:

connecting gates
AND 82, 84, 99
IF 33, 29, 99
OR 17, 22, 44
output

monitor 55
plotter 22, 88
reports 14, 28, 56

There are two ways to designate a target in Doc-To-Help: (1) you can highlight the selected text, or (2) you can type the targeted words through the Tools-Indexing option.

If you want to index a section that deals with a concept, but that concept is not named explicitly in the text, you can highlight a few random words in that section for use as a target. The tag you create for that target can be a general concept, such as "creating hypertext links" or a more specific name.

When you use Doc-To-Help to create online help, the index tags (and the Table of Contents entries) are transformed into hypertext links, which cause the program to launch (jump) to the linked text when clicked. So, if you click "printing reports" in the online index, Doc-To-Help automatically takes you to that section of the document.

Summary

The flexibility of Doc-To-Help makes it possible to produce both printed documents and online Help files from a single source. If you like, the manual and its corresponding online Help file may look completely different but, if you prefer, each can contain different information. Doc-To-Help allows you to mark text and graphics as "Document-only" or "Help-only" and, of course, the index entries (in the text) and the hypertext links (in the online Help file) are modified automatically.

You don't need to be a software developer or technical writer to use Doc-To- Help. However, you should have Word for Windows. You won't need any additional software to run Doc-To-Help, which includes the Microsoft Help Compiler. Doc-To-Help gives you many options. You can create either printed documents or online documents or both. You can convert a printed document to an online document with hypertext links. You can make both the printed and online versions look the same and contain the same information. Or you can have different information in each document. That's a lot of choices.

For more information, contact Lori Lathrop at Lathrop Media Services.