Indexing user manuals & concordance files

[Stuart Burnfield <slb -at- FS -dot- COM -dot- AU>]

Charles Good <good -at- AUR -dot- ALCATEL -dot- COM> wrote:

> Another technique used is to compile a key word list and then use a
> find-the-phrase utility to locate (by page number) every occurrence of
> each word. This method was used by word processors such as Wordperfect
> 5.1 (called concordance file indexing). The problem with it is you do
> not want to denote every occurrence, just the key sections. Therefore,
> you can use this method to help double-check your thoroughness in
> finding "all" the pertinent entries.

Concordance file indexing: a powerful servant but a dangerous master.
I believe it's impossible to produce a usable index by relying on a
concordance file alone. The hard pressed rookie author/indexer may be
tempted to let the CF index every occurrence as a quick & dirty solution,
on the theory that 'more is better' and the reader can work it out.
Don't -- a sloppy index will undo your 200 pages of hard writing work.

A CF won't do the job for you. The good news is that, as Charles says,
it can help _you_ to do the job better.

A CF is great for phrases that you want to index under the same heading,
every time they occur. There probably won't be many of these. Let's say
that the phrase 'bottom line' appears eight times in a book. I might want
three of these to be indexed under 'Bottom line', one of these also to be
indexed as 'Balance sheet:bottom line', another as 'Lines:bottom' and one
other under 'Liposuction'. You can't do any of this with a CF.

I think up candidate phrases by skimming the software, the glossary and
the TOC.  I use a CF to do a first pass through the book, tagging every
occurrence of each word or phrase and generating a draft index. Then I
search on-line through the tags for each entry (such as 'backup method').
Then I sort the phrases into groups:

- index every occurrence of this phrase under the same heading
- index nearly every occurrence under same heading
- index under assorted headings
- create an index cross-reference ("Liposuction: see also Backup method")

Because I'm looking at every occurrence of a phrase at one time, I find
it easier to be consistent but at the same time make useful connections
with other phrases.

Example: p89-91 is a topic devoted to backup methods. Easy - one entry
for that page range. But the CF also reveals the phrase 'backup method'
on pages 33, 164 and 167. The reference on p164 isn't very useful but
p33 introduces backup methods, and p167 explains how they relate to tape
formats. I make a note to tag these last two entries under appropriate
headings.

After I've been right through my 'first pass' index, I have:

- a much smaller CF that I will use to automatically tag every occurrence
  of these words and phrases
- a list of index cross-references ('See X' and 'See also X' entries)
- specific entries pencilled in on the printed copy  ('Tape format:and
  backup method')

I revert to a saved copy of the document from before I did any tagging
and indexing. I do another tagging run with my final CF and tag the
other entries by hand.  If there is a phrase that is nearly always
indexed, sometimes I cheat and put it in the CF, then use the WP's 'find
and replace' to delete the tag for the one or two occurrences that I
don't want.

It works for me, anyway. Hope this helps someone.

Regards
---
Stuart Burnfield (slb -at- fs -dot- com -dot- au)        Voice: +61 9 328 8288
Functional Software                     Fax:   +61 9 328 8616
PO Box 192
Leederville, Western Australia, 6903