Single Source Indexes

Many publishers of technical material are now publishing in more than one format, e.g. print, Adobe Acrobat (PDF), HTML, HTML Help and XML. Typically, a master document is first created in a package such as Adobe FrameMaker or Microsoft Word. The master document is then converted into different formats for publishing.

Indexes are often the Achilles heal of such a process, because indexes can rarely be converted like regular material. Indexes usually have to be regenerated or recreated within the new format rather than simply converted from an existing file.

Single source indexes must address two major issues:

how to handle multiple reference locators (e.g. page numbers or hypertext links) following an index heading
where the reference locators should link back to in the document

In print indexes, an index heading can be followed by several page numbers, but in online indexes what do you use? Some systems insert false “page numbers” (e.g. 1, 2, 3) or symbols (e.g. #). Or, you may only be allowed one reference locator for each index heading. Help systems may use the title from the particular help topic as the reference locator. In this case, the title of the help topic acts as an index subheading or sub-subheading.

Page numbers in print indexes take the user to a particular page where the user then looks for the particular reference. The header and footer on the printed page inform the user of where he or she is. But, online documents (except some PDF files) have no page numbers, headers or footers.

To what should the hypertext links in an online index point to? If they point to particular paragraphs, the user can become disoriented. If the online “pages” are short, it can be better to link to the top of the online page or help topic. If the online pages are long, as can happen when legacy documents are converted to online, then the document headings can be a good choice. Either way, the reference locators in the index may point to different places in the document depending on whether the format is print or online. Also, page ranges used in printed documents make little sense in HTML or HTML Help.

The basic mechanics of creating or generating the index in different document formats can lead to challenges. It’s a wise idea to test your conversion software early. Check that your software handles the following correctly:

“See” and “See also” cross-references
subheadings
headings with multiple reference locators
page ranges
main headings with multiple reference locators where the main heading also has subheadings

Indexes play a key role in successful business and technical publications. Good advance planning and testing are essential for indexes used in single source documents.

Fred Brown
Allegro Technical Indexing
fred.brown@allegrotechindexing.com
(613) 728-9373

April, 2002
Allegro Time!