Indexing Summary

Subject: Indexing Summary
From: Paula Reynolds <PAULAR -at- HISPEED -dot- MHS -dot- COMPUSERVE -dot- COM>
Date: Thu, 16 Sep 1993 17:03:24 EDT

Sorry this is so delayed, all, but my wonderful place of employment told
me I couldn't subscribe to any listserves since it cost so much money
(per call). PLEASE! I think I'm going insane! Anyhow, here goes:

- Paula
Hi-Speed Checkweigher

----------
From: Joan Stout <sasjcs -at- UNX -dot- SAS -dot- COM>

(del)

The logic - put *very* simply - is that every concept/idea/fact that is
discussed in the book should be accessible to the reader via the index.
I like these ideas from _Introduction to Indexing and Abstracting_:

"A good book index sorts and classifies the contents
of the book into a form that allows immediate access to
specific items a user needs."

"An index to a book is a self-contained information
retrieval system. The information database is between
the covers of the book, and the purpose of the index
is to recall the information with an acceptable level
of precision."

(del)

I put together the following list for a response to the misc.writing
newsgroup:

The traditional indexer's "bible" is _A Manual of Style_, commonly
known as the Chicago Style Manual or just "Chicago." It has a lot of
helpful information on indexing. However, it is incomplete and some of
it is outdated. They are currently working on a revised edition.

Another reference book with a section on indexing is _Webster's
Standard American Style Manual_. It complements "Chicago."

ANSI also has an indexing standard, and it is also being revised. Most
book indexers don't consider the current edition very helpful. As I
recall, it applies mostly to database indexing and thesauri.

_Indexing and Abstracting in Theory and Practice_ by F. W. Lancaster
(ISBN 0-87845-083-1) is a textbook. It won the 1992 award for best
information science book from the American Society for Information
Science. It's strong on theory, not as strong on practical information.

_Introduction to Indexing and Abstracting_ by Donald and Ana Cleveland
(ISBN 0-87287-677-2) has a lot of good information, including practical
material.

_Indexing from A to Z_ by Hans Wellisch (ISBN 0-8242-0807-2) is my
current favorite. The blurb I have here says it's "an encyclopedic work
covering basic indexing techniques, author-publisher-indexer relations,
business considerations, editing and proofreading, computer-assisted
indexing, and many other topics..." This book has lots of practical,
how-to information, and it's the one I refer to the most. However, like
almost all books on indexing, it's short on information about indexing
technical material.

Information specific to technical material, such as software user guides,
is more difficult to find. I've seen articles in _The Editorial Eye_ and
in the newsletter of the Society for Technical Communication (STC).
Also, check the proceedings of the annual STC conference. They usually
have at least one paper or workshop on indexing.

Consider joining the American Society of Indexers (ASI). They have many
resources for indexers, including a newsletter and a journal. They also
have many local chapters, and the chapters frequently hold workshops
and seminars. For information: ASI Office, Kathy Caldwell, P.O. Box
386, Port Aransas, TX 78373, (512) 749-4052, FAX (512) 749-6334.

To get information on ASI publications, contact the ASI Publications
Sales Office at the same address. Publications include _Freelancers on
Starting and Maintaining an Indexing Business_, _Generic Markup of
Electronic Index Manuscripts_, _A Guide to Indexing Software_,
_Indexing: A Basic Reading List_, Indexing Biographies and Other
Stories of Human Lives_, and _Indexing from A to Z_.

I don't know of any exercise books, except for one that's included with
a correspondence course. The course is Basic Indexing, offered by the
Graduate School of the USDA. The workbook is very good, and I've used
it many times to train indexers. The address is
Graduate School, USDA
Correspondence Programs
South Agriculture Building, Room 1114
14th St. and Independence Ave., S. W.
Washington, D. C. 20250
(202) 447-7123

To subscribe to the listserve indexing group, send a message to
LISTSERV -at- BINGVMB -dot- BITNET The body of your message should say
subscribe INDEX-L your name

pjr: Joan later corrected the address; I've corrected it in this text.
----------------------------------------------------------------
Since I put this list together, the American Society of Indexers began
offering a book about indexing technical material. My copy hasn't
arrived yet, so I can't comment on it. I don't remember the title, and
my ASI newsletter is at home. If you want more information on this
book, send email.

-----------------------------------
From: sanders_j -at- TBOSCH -dot- DNET -dot- GE -dot- COM

(del)
My best advice on building an effective index is: SPLATTER. Throw
everything
you can into the index, with as many different references for the same
information as possible. This will allow people to find the information
their looking for under the term that THEY think it should be under, not
just YOUR term for it. There was a discussion about this a while ago, and
if I can find the file, I'll send it along. Someone recommended that the
index should take up about 5-10% of the manual. You should reference all
commands (or keywords, or whatever), not just under the heading
"Commands"
(for example), but each command should also be found on its own. That
way people can find it under "Commands" and under *textrun_* (or
whatever).

(del)

-------------------------------
From: kendal -at- autotrol -dot- cuc -dot- ab -dot- ca (Ken d'Albenas)

(del)

You know your product. Create an index the "tad simplistic" way, then
do a user test. Anything that the user needs to know and can't find
in the manual - add it to the index.

One tip (indexer's rule of thumb): if an index entry has more than 5 page
references, take action. Either subdivide the entry, or take a hard
look at how information has been organized in your manual.

---------------------------
From: Paul Trummel <trummel -at- U -dot- WASHINGTON -dot- EDU>

I suggest:

1. Read "The Chicago Manual of Style" Chapter 18 Indexes.

2. Adapt the word processor index program attributes to meet the Chicago
parameters and your own need. Indexing forms an integral part of, and
a concurrent function to, writing. Therefore, set up the word processing
parameters while outlining and capture the information as you write or
revise.

3. Professional indexers serve a useful function in that they can
sometimes introduce objectivity. However, the author remains in charge
and
more familiar with the subject matter. Many writers abdicate
responsibility for indexing by delegating to professional indexers
who only know electronic index algorithms and not the subject
matter. These authors live to regret it and usually spend the night
before the
press run trying to cut and paste.

-------------------------
From: Susannah Skyer <susannah -at- sco -dot- COM>

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: Indexing advice
Next by Author: IPCC (Looking for inexpensive lodging)
Previous by Thread: Simple question and/or
Next by Thread: Re: History of technical writing


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


Sponsored Ads