I am overjoyed that the same quality of index as described in the above-referenced article is possible with Dr.Explain.  It still takes a lot of work -- as I said in that article, there really is no capturing this kind of required human intelligence in a consumer-market computer program yet.  But the fact that Dr.Explain makes it do-able for your (possibly-extensive) help document makes me VERY happy!  And in my opinion, it is MUCH easier to do with Dr.Explain than with Microsoft HTML Help Workshop, and is a comparable effort to indexing with Adobe Pagemaker, which has an excellent indexing scheme, but is more geared toward printed, page-oriented documents, whereas Dr.Explain is more geared toward Help Files and/or web-based reference documents, and of course, has many tools that make it very easy to document software.

 

Dr.Explain uses the term "keywords" when referring to index entries, as does Microsoft HTML Help Workshop.  In Dr.Explain documents, every time you read "keyword", think of "index entry" and you'll have it.  And the Keywords display is the index itself.

 

As you build an index (a.k.a. keywords hierarchy), Dr.Explain displays the entire index in the lower-left corner of the application, under the "Keywords" tab.  Every time you display a different topic, the entire index is re-displayed, with keywords that connect to THAT topic shown with a checkmark.  Unfortunately, a real, quality index quickly gets too large for that display, but three things can make this easier to deal with:

 

1. You can make the display longer by raising the divider bar between the TOC and the keywords display.

 

2. If you have certain types of flat screen computer monitors, you can rotate your monitor (or one of your monitors) so that it is oriented vertically.  (Those monitors and sometimes video controller cards come with software that enable the image to be rotated to accommodate this -- a necessity in this case.)  If you can do this, then you can make your keywords list significantly longer and thereby easier to work with. The more of it you can view, the easier it will be.

 

3. If you are only concerned about seeing the keywords for the topic being displayed, there is a "filter" button in the Keywords toolbar that enables you to do this.  However, in my experience in building indexes, you will need to switch back and forth frequently so you can see how your new index entries impact the overall index, and this also gives clues as to where other index entries might be needed.  Fortunately, switching back and forth between these views is literally as easy as clicking the filter button.

 

4. There is another quite powerful filter button called "Keyword references".  Placing focus on any one keyword and then clicking this button displays the TOC tree hierarchy with the topics linked to that keyword checked.  What is so powerful about this is that you can add or remove links between that keyword and other topics right in that dialog box.  This is exceptionally handy if you think of a new index entry that is going to be needed, and already know it will need to be linked to several topics.  You can do all the linking right there in that dialog box.

 

Note: Adobe Pagemaker enabled you to view the index in a multi-columnar format, thus enabling you to use most of your screen to display the index, which works very well to help see a lot of your index at once.  Thus, Adobe Pagemaker has this as a slight advange in this case (but you can't make help files or web-based reference documents directly with Adobe Pagemaker).

 

To make a 2- or 3-level index, the simplicity of building it in Dr.Explain is simply adding all the index entries at all levels, just like in the examples in the indexing article.  If a CONTEXT index entry (example: "installation" and "software" in the below example) is not DIRECTLY connected to the topic you are indexing, then UNCHECK IT.  If it does relate directly to the topic being indexed, then CHECK IT (or leave it checked if you just created it).  As you encounter other topics that should also be linked to that keyword, then navigate to that keyword in the already-existing index entries and check it while that topic is being displayed (or use the "Keyword references" dialog to do so directly from that keyword).  That creates the connection between index entry (keyword) and help topic.

 

Let us take an example about software installation where one topic would be about the "path option" ("path" means hierarchy of folders where the software would be installed).  While Dr.Explain was displaying that page, your keyword list might look like this:

 

 

Here the "x" would be represented as a check in the checkbox next to the keyword entry "path option".

 

For a topic that contains the "feature options" discussion, if it is a different topic in your Help file, the keyword display would look like this:

 

 

When you switch back and forth between the above two topics in the TOC tree, the keywords display will toggle back and forth between the above two displays.

 

If yet another page contains both discussions, then the keyword display will look like this when that topic is displayed:

 

 

In this example, the keywords "installation" and "software" will serve their purpose as "context" in the index.  When the user double-clicks on them, the Windows HTML Help engine correctly displays this message:

 

"To locate information about this keyword,

please select one of the subentries in the list."

 

(Caution:  there is, at this writing, a bug in the HTML Help engine that causes it to sometimes jump to another entry in the index -- to place your keyboard focus in a position in the index "close to" the name of the context index entry you double-clicked on.  Thus, it remains a good idea to test every single context index entry by double-clicking it in your final product.  If this happens, it is not difficult to "populate" the context keyword with links to each of the links that are provided by subentries through the "Keyword references" dialog box discussed above.)

 

If a keyword is related to more than one topic, then when the user double clicks that keyword in the index, the Windows HTML Help engine correctly displays a dialog box with a list of all topics connected to that keyword for the user to select from.

 

Finally, I strongly suggest a final test of your completed index.  Generate the CHM file and double-click every single index entry while asking yourself: "Is this what I would expect to happen as a reader?"  In most cases you will find places to refine your index and possibly re-organize it a bit.  This is good because when you deliver your final product, your index will be closer to perfection. It's really HARD to find good indexers, so this will make your work that much more valuable.