digest of replies to indexing query

Subject: digest of replies to indexing query
From: "Genevieve Roberts" <gen -at- qrtz -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 21 Oct 2002 16:07:31 -0700

Many people have asked me to forward the replies that I received to the
query that I made about indexing, and one person suggested I make a summary
of the info I received.

Rather than blending the replies into a summary, I think I have just enough
time this afternoon to copy and paste a "digest" of the replies. I think
this will be a good thing, since if you want more info you will have the
names of the authors of the postings.

Here you go:


Not that I'm a great indexer, but I really like the book "The Art of
Indexing" by Larry S. Bonura. It is food for thought for those of us that
don't index too often, but want to learn more when we do.


Eric Thomas [erict -at- installshield -dot- com]


I did some looking a while back for similar information and found these
sites provided considerable help and insight into indexing.


Spreadbury, David C. [David -dot- Spreadbury -at- marconi -dot- com]


Hi Genevieve,

The Chicago Manual of Style has a long section on indexing that is very

Bye for now,

Naomi Scott [nscott -at- sierrawireless -dot- com]



Good possibilities for entries are keywords in your main headings.

Think of the most common words to describe the concepts discussed.

As you read, ask yourself: "If I were a user trying to find this info, what
word would I look under?"





Ann Hastings [Ann -at- qss -dot- COM]


Just a suggestion: one of the books I like to use is called The Art of
Indexing. It gives very good ideas & dos/don'ts for Indexing.

Mintee Mint [minteem -at- yahoo -dot- com]


One indexing book that I've extremely helpful is "Indexing Books," by Nancy
C. Mulvany.

Here are some general guidelines for indexing:

What to Include in the Index
Include all significant content items in your index. Here are some
suggestions for the items that are probably genuinely "significant":

* Most headings in your manual. The headings are already in the Table of
Contents, but it doesn't hurt to include them in the index as well,
especially ones that are task-related.

* Concepts (for example, paragraphs in which you give an overview of a
specific topic)

* Definitions of major terms

* Procedures

* Pieces of information that you suspect a reader will refer to often (for
example, a particularly useful table)

* Important tips, notes, or perhaps warnings about life-threatening
situations ("Nuclear core, handling meltdowns in")

* Things that generate regular calls to Customer Support

What Not to Index
* Graphics (unless they're significant for some reason)

* Dialog boxes and other UI elements (unless they're significant). Usually
you would index the task that a user performs with that UI element instead
of the element itself. An exception might be a dialog box that users
typically have a hard time manipulating in the software or a vital checkbox
that everyone knows is there somewhere but that no one can ever find.

* Introductory material of the "About This Manual" nature.

Knowing Which Synonyms to Include
The synonyms that you include in the index depend on the document's target
audience or audiences. For example, do Unix and Windows users refer to a
given term in the same way? Do you need to include both terms in the index?
Are both technical and non-technical people going to be reading your
manual? If so, you may need to include synonyms for each group.

The best way to come up with a good set of synonyms is to find guinea pigs
from the appropriate audiences and question them closely about the
terminology they prefer. You could also talk to Training or Customer
Support (or anyone else who has direct contact with a wide range of
customers) and ask for suggestions.


Cheryl Magadieu [leftymagoo -at- attbi -dot- com]



On your request for indexing guidelines, I recommend two reference
books (besides the FrameMaker User's Guide, by the way):

(1) The Chicago Manual of Style. The University of Chicago Press
(14th Edition, 1993)

(2) A Style Guide for the Computer Industry, Sun Technical Publications
(Prentice Hall)

You can't go wrong with #1, for *MANY* reasons, and #2 focuses on the
we face within the 'high-tech' industry. (I found #1 at my local
Half-Price Bookstore
in 'mint' condition.)

Hope this helps.

john -dot- lukes -at- kodak -dot- com


-----Original Message

All-new RoboHelp X3 is now shipping! Get single sourcing, print-quality
documentation, conditional text and much more, in the most monumental
release ever. Save $100! Order online at http://www.ehelp.com/techwr-l

Buy ComponentOne Doc-To-Help 6.0, the most powerful SINGLE SOURCE HELP
AUTHORING TOOL for MS Word. SAVE $100 on the full version and $50 on the
upgrade. Offer ends 10/31/2002 (code: DTH102250).

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.

Previous by Author: thank you!
Next by Author: RE: Dumb warnings
Previous by Thread: Re: techwr-l digest: October 20, 2002
Next by Thread: Would You Like to Be Including in My Upcoming Book?

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

Sponsored Ads