TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Since I received an overwhelming number of responses (28 so far, and
still counting!) for this file, I've decided to post it to the list
rather than send it separately to each requestor. So ... if you have
absolutely no interest in indexing, now is the time to press the DELETE
key :-)
The information below is from the _Participant's Workbook_ for my
two-day workshop -- Indexing Skills Workshop for Technical Communicators
(copyright - Lori Lathrop, 1994):
A FEW RULES FOR DEVELOPING INDEX ENTRIES
Rule #1: Be anal retentive ... and follow the rules!
Rule #2: Read the book, cover-to-cover, first -- especially if you
are not the author. Don't even make notes in the margin
on your first read-through. Just read and absorb the author's
terminology, the organization of the book, and the relationship
of various topics. Then, and only then, should you begin
developing index entries.
Rule #3: As yourself, "Who is the audience for this book?" If you
don't know, ask someone who does. Create index entries that
will be meaningful to that audience; if the terminology in the
book is likely to be unfamiliar to readers, it may be necessary
to think of synonyms and use See references to point to the
author's terms.
Rule #4: Create entries in noun form, preferably singular. Some
examples of entries that could be inappropriate in singular
form are: messages, printers, screens, and commands.
Rule #5: Arrange all entries alphabetically. In an effort to keep
related topics together, you may occasionally be tempted
to break this rule, but ... don't do it.
Rule #6: Ignore the following when alphabetizing entries: apostrophes,
articles and prepositions, titles (such as Mrs., Senator,
Reverend) when alphabetizing entries.
Rule #7: Be concise. Eliminate unnecessary entries if they can be
consolidated into a more general entry.
Rule #8: If a primary entry has only one subentry, eliminate the
subentry and include the page reference with the primary entry.
Rule #9: If entries have more than 3 page references, it may be a good
idea to create subentries that would be more helpful to readers.
Rule #10: Be sure that subentries are concise and that they "read back"
properly to primary entries. Do not use unnecessary articles
and prepositions.
Rule #11: Use See and See also references when appropriate. (See refs
point to preferred terms; See also refs point to related info.)
Rule #12: Consider ways to expand the index and improve readability by:
(a) using subentries as primary entries; (b) creating additional
entries by rearranging the word order of existing entries (that
is, when the new word order "makes sense"!); and (c) including
synonyms for important terms and concepts.
Rule #13: Use capitalization, punctuation, and other stylistic conven-
tions consistently. Most importantly, follow the publisher's
guidelines.
Rule #14: Place page references (locators) with the lowest-level entries;
if a primary entry has secondary entries, use page references
with the secondary entries only. Likewise, if a second-level
heading has tertiary (third-level) entries, use page references
with the tertiary entries only.
Rule $15: Ignore apostrophes; treat words with apostrophes as one word.
Rule #16: If different words have the same spelling, arrange them in the
following order: person, place, subject, title.
INDEXING PITFALLS
Perhaps the biggest problems occur when an index is not as comprehensive
as it should be. Ideally, the index should contain entries that point to
every "useful nugget" of information. Readers feel most frustrated when
they are unable to find an entry in the index, especially when they know
that the information is "int he book somewhere." Then they are forced to
look at other retrievability aids, such as the table of contents or
headers and footers, and they inevitably resort to "eyeballing" the text
in hopes of stumbling upon the information they need. Of course, not all
users have the time or the patience to do that; they're the ones who call
a Hot Line or Customer Service for help and, by that time, they are not
happy customers. The moral of this story is simple: A well-written,
comprehensive index increases customer satisfaction and reduces costly
product support time because it makes your products easier to learn and
use.
A less common pitfall but one that is just as frustrating for users,
especially those on a "fishing expedition" through the index is to find an
interesting index entry, turn to the page in anticipation of finding
something fascinating (or, at least, interesting), and then discovering a
dead-end because the information is not there! At that point, you have
another unhappy customer -- and, perhaps, a customer who has lost
confidence in both the book and the product.
LORI'S GUIDELINES FOR EDITING INDEXES IN TECHNICAL DOCUMENTATION:
The index provides a good editing tool for checking the organization of a
document because it indicates if information on a particular topic is
scattered throughout the text or if two topics of similar significance are
not given equal weight in the documentation. Also, it reflects any
inconsistencies in terminology, and it can often make omissions obvious.
For these reasons, developing an index as you write can help you avoid
some last-minute revisions of the document.
As you edit an index, ask yourself the following questions:
1. Is it comprehensive. Does it provide one or more access points
for every "useful nugget" of information?
2. Is the size (length) of the index at least 5% of the document?
3. Have you included appropriate entries for:
Chapter headings
Table and figure captions
Items in tables and figures
Examples and figures
Definitions or new terms
Acronyms and abbreviations
Synonyms
Main topics of paragraphs
Important concepts
Warnings or restrictions
Main tasks
Main features of a product
Scren names, field names
Functions, commands, parameters
Screen messages
Menu options
Information in Appendixes
Glossary (definitions)
Bibliography (references)
Footnotes
4. Are relevant synonyms included?
5. Is all capitalization and punctuation used correctly?
6. Have all extraneous words been eliminated?
7. Have all unnecessary articles, conjunctions, and prepositions been
eliminated?
8. Does each See reference refer to an entry that is followed by
subentries that contain proper page references?
9. Are all subheadings correct subdivisions of the keyword?
10. Are all subheadings logical and consistent?
11. Is the number of subentries under the various forms of the same topic
the same?
12. Is the terminology consistent?
13. Do uppercase text srings (such as commands) contain qualifiers?
14. Are acronyms and abbreviations indexed both ways? For example:
API (Application Program Interface)
and
Application Program Interface (API)
15. Do topics of similar significance and complexity have proportionate
index entries?
16. Do primary entries have a sufficient number of subentries to lead
readers to more specific information?
17. Do entries that begin with a numeric character appear in the
alphabetical portion of the index as though they were spelled out
as well as in the section for special characters and numeric entries
preceding the alphabedical section?
***
Stay tuned for Part 2 of the INDEXFAQ file ....
Lori Lathrop ---------------> INTERNET:76620 -dot- 456 -at- compuserve -dot- com
Lathrop Media Services
P.O. Box 808
Georgetown, CO 80444
(303)567-4011 -- home office
(303)567-9306 -- fax
