Help Authoring Woes: Index As You Go

Monday, November 24th, 2008 | RoboHelp / Flare, Technical Communication

The prevalence of search engines hasn’t pushed out indexing yet. I’m not an avid fan of indexing because of the time involved in putting one together, but a search capability is not always what users will employ to find information.

Search functions are generally included in help systems and is built in to Adobe Reader, so usually, users will not neglect the search with the excuse that there isn’t one. Like other conventions from when the only documentation was a manual, however, indexes continue to be a standard component, and I’m sure some people use them out of habit. But in cases where you provide a PDF and users print it, there’s no search, and it’s up to the table of contents and the index to tell them where to find what they’re looking for.

I search first myself, but because there’s still a place for indexes, I still include them. Perhaps due to my attitude toward them, though, I tend to let them slip sometimes, especially in my help systems. Last week and into this week, I’ve had to spend some time in one of my RoboHelp projects getting my index fully fleshed out. The deadlines—and working on other projects—had kept me busy for so long that the index became the ball I dropped.

My neglect has come back to bite me. I’ve realized that if I had but added to my index one topic at a time, I wouldn’t have this problem. It would have been so easy when I finished a topic to review it for keywords and associate that one topic with them. So I’ve resolved to make it my standard practice to index a topic as soon as it’s ready to go into the project repository.

In fact, the best way for me to manage this is along with a conditional build tag that I use. I have a tag in my project called “Unfinished” that I apply to topics that are in progress. My output excludes anything with this tag so that if I have to update other content while new topics are still in the works, they are automatically kept out of the application. A good guideline—no, a rule—would be to index the topic before I remove the conditional tag. Since I have to remove the tag to include the new topic, I enforce the indexing of the topic.

Thorough indexing is one of the signs of a technical communicator who has taken the time to give the users the resources they need. It may not be noticed when it’s there because it’s expected and taken for granted, but when it’s not there, someone will complain (or at least grumble and curse the help author for omitting it). There may be some grumbling out there over my incomplete index, too.

Share This