Tech Doc Indexing

The Challenge

Frequently updated product lines, and thus frequently changing support documentation
Automatically generated indexes based on embedded markers or tags
Limited or no time to edit generated indexes prior to publication
Single sourcing of documentation such that editing of indexes for compiled documents is impossible
Accommodation of translation/localization and restrictions on outputs such as help file indexes
The result--incomplete and badly formed indexes that are virtually unusable

The Solution

Indexing training for writers
Standard vocabulary list for index term selection
Indexing style guidance added or revised for the company documentation style guide

The Process

Timing--about six months for planning, training, vocabulary development and style guidance
The steps to indexing success:

1. Planning and budgeting—I'll talk about what you'd like to do, and the cost thereof. You consult with your business divisions/units to garner support and then get back to me with a commitment to all or part of the solution.

2. Textual analysis—I review the materials that your writers produce (user guides, technical repair manuals, etc.). I normally index a certain number of documents myself to see what the writers may have missed, and then for a more comprehensive look, I incorporate terms from the existing indexes of documents I haven't worked on myself. This step provides a good cross-section of vocabulary to include in the standard list.

3. Standard vocabulary list—I create the list (it looks like a regular index with some brief instructions on when to post a term at more than one synonym or make cross-references) and then pass it on to you for the subject matter experts to review. They know better than I do how different subjects may relate to each other or not within the scope of your documentation. There can be multiple passes in the review process; it's up to you how much fine-tuning you want to do.

4. Training—Either before or after the review of the standard vocabulary list, I will use the knowledge and materials I have to tailor a training program that goes over basic indexing conventions and provides hands-on exercises to reinforce best practices. I can also add step-by-step instructions on embedding index markers in Adobe FrameMaker, Microsoft Word, or XML if folks are not yet familiar with the tools. My goal is to help the writers build better indexes faster and more easily.

5. Follow-up maintenance of standard vocabulary—You will need to put into place procedures for submitting new concepts to the standard list and redistributing the list, probably every six months or once a year. You can do this in-house, or consult with me and have me review the new draft to make sure that new concepts are integrated correctly into the whole. For a small fee, I should be able to arrange for a look at your new list and turn it around to you within a week after you submit it to me.

6. Ongoing training for new writers and editors—You can arrange for in-house passing on of the indexing wisdom to new writers and editors, but I am also available to provide a refresher workshop (at a reduced rate) to guarantee the continuation of quality information access through indexing for your product users.