Indexing advice

Subject: Indexing advice
From: Susannah Skyer <susannah -at- SCO -dot- COM>
Date: Tue, 7 Sep 1993 15:54:38 +0100

Here's an article on indexing from our in-house style guide.
Some of this is pretty SCO-specific, but other bits may
be of interest.

Enjoy,

Susannah Skyer
Unix Doc Project Lead
SCO EMEA (Europe, Middle East, Africa)
---------------------------------------------------------------------
Indexing

Indexes are among the most important parts of any documentation. Very
few users read documentation from beginning to end. Most read the
sections they must, and rely heavily on indexes for needed guidance.
Consequently, the index must be very carefully and completely
constructed.

When creating an index, consider:

+ what terms to index

+ how to word each entry

+ where to insert each entry in the text

+ which synonyms to use

+ where to use page ranges

When you are creating and reviewing your index, keep the reader's needs
foremost.

First, recognize that an index can have a very diverse set of readers,
depending both upon the type of guide and the level of experience of the
users. Therefore, your index needs to include terminology and synonyms
that respond to the needs of all users, from the novice to the expert.
Ask reviewers and users to help you come up with appropriate terms.

Check the index.nouns and index.verbs files in the dochelp directory and
take from them what you can. If you have suggestions for new entries in
those files, please send them to your site editor.

Remember the importance of including keywords, commands, menu options,
glossary terms and so on. For assistance, look at your section headings
and use them to create appropriate index entries.

Finally, try to be concise in the wording of entries. The goal is to
point readers to the desired information, not to outline it.

Steps in creating an index

The process for creating an effective index generally consists of the
following steps:

1. Writers create index entries and generate a preliminary index.

2. Writers gather tech review comments on the indexes, edit the entries,
and generate a revised index.

3. Editors evaluate and edit indexes both technically and stylistically.

4. Writers incorporate editorial revisions and format indexes for
typesetting.

Several iterations of the first three steps may be necessary in this pro-
cess.

Style conventions

Our basic style conventions require:

+ In main entries, capitalize the first letter of the first word and
proper nouns. Entries not capitalized include:

- command names (which should be immediately followed by their
manpage section reference, for example: tar(C). You will need to
manually reduce the section letter point size with s-1.)

- filenames

- routine names

- any others where altering the case may create ambiguity or
confusion

+ In subentries, capitalize only proper nouns.

+ In page ranges, use the BEGIN and END arguments to the .XX macro. If
you see:

Entry, 1,2,3,4,5,6,7

and the text is actually a continuous discussion, repeated .XX
entries have been used, and these should be changed to a single
BEGIN/END pair. See the sco.mac User's Guide for more information.

+ Avoid index entries that break over more than one line. As a general
guideline, limit entries (including subentries, but not page numbers)
to 35 characters, when possible.

+ Make sure that the spelling and capitalization of the entries is
consistent. First check the style guide's vocabulary list; if the
word in question is not listed there, use the first (preferred)
spelling in the current Webster's New Collegiate Dictionary. Ask your
site editor if further clarification is required.

+ Expand acronyms only when this aids access. If expanded, an acronym
should only be expanded in the main entry (not repeated in the
subentries).

The following style guidelines are automatically enforced by the sco.mac
and mkindex tools and should only require spot checking:

+ alphabetization

- special characters appear at the beginning of the alphabet by
default, although this is configurable; see the sco.mac guide.

- when / (slash), \ (back slash), and . (period) are used to indicate
filenames, macros, or other special uses, they are ignored in
alphabetizing and filed according to the succeeding letter.

+ hyphenation

+ italics on See and See also

+ indentation of subentries


Questions for reviewing an index

The following list is designed to provide a starting place for reviewing
an index.

+ Are there missing entries? Have all important subjects been covered?
For assistance, turn to the table of contents and check to see that
the titles are represented in the index. You should also do a random
check throughout the document, further ensuring that the subjects are
incorporated properly into the index.

+ Are entries logical and meaningful? That is:

- Would a reader look under this entry for the subject?

- Does the entry use the same language as the text (that is, in terms
of punctuation, capitalization, spelling, and wording)?

- Are entries consistent with index.* files (in your local dochelp
directory)? If an author's original wording varies from the index.*
files, the term should be indexed under both wordings. (If this
produces a sloppy looking index, for example, near-identical terms
one after another, editorial discretion may be used.)

+ Are the entries in noun form whenever possible? Gerund forms should be
limited to qualifying terms and subentries wherever possible.

For example:

Changing colors

should be:

Colors, changing

and

Creating portable data with XDR

should be:

XDR, portable data creation

or perhaps:

XDR, creating portable data

The goal here (and with the following guideline on bringing keywords
forward) is to use the clearest term possible as the first-level
entry.

+ Are inversions done correctly, bringing key words forward? For
instance, consider the following example from development system doc:

Data structures, x.out symbol table

An improvement would be simply:

x.out symbol table

Otherwise, the specific and useful entity is hidden behind a general
and (in indexing terms) useless one.

+ Are the inversions useful? For example, if you have in your index:

Authentication, service dispatch routine

you may not want to invert this, placing ``service dispatch routine''
first, because you believe ``Authentication'' is a more useful
keyword. However, a good rule in these cases is to index under both
forms to provide greater keyword access; that is, list both:

Authentication, service dispatch routine

and

Service dispatch routine authentication


+ Do subentries have a logical relationship to main entries? Does every
subentry make sense under its main entry? (This is a point you would
want to ask subject matter experts to review.)

For example, do the following subentries all make sense under
``Mode''?:

Mode
changing
single user
system maintenance

One way of clarifying this example would be:

Mode
see also chmod(C)
file, changing
system (init level), changing
Single-user mode
System maintenance. See Single-user mode


+ Is the wording of subentries consistent, both for subentries under the
same main entry and for all main entry/subentries groups throughout an
index? For example, the following subentries could be reworked
slightly so that gerund forms were used throughout:

Button binding
configuring
context
creating
event definitions
specifying resources

One revision might be:

Button binding
configuring
context
creating
events, defining
resource, specifying

Once you have creating a set of subentries for one entry, similar main
entries should have similar subentries. For example, the following
listings of serial communication topics could be improved by using
similar (if not identical) terminology in the subentries.

cu(C)
dialing out
login sequence
modem connection errors
troubleshooting modem
UUCP
dialer program
error messages
login
modem
problems


+ Are main entries containing many page locators broken down into
subentries?

A rule of thumb from the Chicago Manual is that main entries with more
than five or six page references should be broken into subentries.

+ Are there subentries with the same page locators under the same main
entry? If so, combine the entry and the subentries.

+ Are main entries with many subentries regrouped into main entries?

If there are a large number of subentries under one main entry, the
subentries should be regrouped. The following example would be far
more usable with less subentries. This could be achieved by
eliminating similar subentries and promoting the most important
subentries to main entries:

Modems
auto-answer
baud rate
checking baud rate
checking /etc/gettydefs files
checking modem cable
configuring
connecting
data compression
dialers
Dialers file
dial-in
dialing configuration
dial-out
editing /etc/inittab
error correction
Hayes (and compatible)
incompatible
installing
local network switch
login sequence
null modem
pin connections, cabling
planning
printer
printer connection
problems in UUCP
speed conversion
supported
switch settings
telephone line
testing
testing phone line
Trailblazer
troubleshooting
UUCP use
volume

Another option is to introduce subsubentries (third-level entries).
Generally, this is discouraged, because it adds complexity to the
index, but in dire cases, such as the example above, third-level
entries could be an improvement.

In some cases of excessively long lists of second-level entries under
a particular first-level entry (as in listing every UNIX command under
'command'), you may want to produce a glossary of commands and insert:

.SX "Commands. See Glossary of commands, page 321"


+ Does each main entry have two or more subentries?

If there is only one subentry, combine the subentry with the main
entry.

+ Are entries appropriately specific (that is, neither too general nor
too detailed)?

+ Are cross-references used correctly? That is:

- Look for (and eliminate) cross-references that lead nowhere.

- Do not refer a user to another entry that includes less than three
page locators. In those cases, just double post.

- Ensure that all cross-references provide additional information.

- Evaluate again whether there are any missing entries.

_________________________________________________________________________
NOTE Except for cases where an urgent fix is required, writers
should edit their index entries in the troff source files
instead of the formatted index file. This ensures that the fix
is incorporated when subsequent indexes are generated.

In this event, the source file should be opened again and the
index entry modified once the urgent work is done, so that a
reprocessed index will duplicate the index urgent fix.
_________________________________________________________________________


Technical review and usability testing

Proposed index entries should be technically reviewed alongside the
document they index. Ask reviewers to comment on the terms you already
have - would the reader search under these terms? Also (and you may want
to do this before you've shown the reviewers your list of terms), ask
them to brainstorm terms that should be indexed.

You can work this into a kind of usability test by asking a spectrum of
reviewers (find those representative of your audience if possible) to:

+ review a small chunk of new doc (highlight what's new)

+ note which terms from their review doc they believe should be indexed

+ look in the index of the doc and see if their terms were there

+ note ``hits'' and ``misses'' on form

Another type of usability testing you can do is:

+ pull random passages from your doc (you can write an awk script or
other program to do this) - these passages should contain no headings,
page numbers, or other locators

+ give testers some random passages, plus a complete index, plus a
complete book (containing all random passages, but in their real
order, with headings and page numbers)

+ monitor the testers as they attempt to locate the random passages in
the index; ask them to think out loud as they do

+ record their ``hits'' and ``misses,'' along with any other information
that will help you to improve the index.

(These usability tests were presented by Deborah Swain of IBM at 1993
Society for Technical Communication conference.)

See also


+ Docsplit

+ .err files

+ sco.mac code

+ sco.mac User's Guide

+ the indexing chapter in the Chicago Manual of Style

+ IBM's Information Development Guideline: Indexing (available from your
local indexing team member)

+ Proposed American National Standard Guidelines for Indexes for Infor-
mation Retrieval (available from your local indexing team member)


Previous by Author: Typographical conventions
Next by Author: Quality: A typesetter's checklist
Previous by Thread: Re: Indexing advice
Next by Thread: Re: Indexing advice


What this post helpful? Share it with friends and colleagues:


Sponsored Ads