Re: Indexing- Best Practices

Subject: Re: Indexing- Best Practices
From: Peter Neilson <neilson -at- alltel -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 22 Sep 2003 21:02:58 -0400


Nilesh,
A good cookbook, such as the classic Rombauer and Becker "Joy of Cooking,"
will provide an example of an excellent index. Below I list some hints
and traps.

- Be wary of "See" entries. "See also" is ok, in moderation. It's very
frustrating to the reader to be sent to another spot in the index when
the original entry could have simply given the page. (Rombauer and
Becker say, "Also see" instead of "See also.")

- Try to anticipate how the reader will use the document. Some people will
look up chicken soup under "chicken" and others under "soup," so both
entries are needed. Sometimes the reader will try to find an alternate
term that isn't ever mentioned in the text, and this is a valid situation
for a "See" entry. Rombauer and Becker: "Dried beef, see Chipped Beef."

- Use only two levels in the index, even if your software allows more. There
is never any excuse for a third level. Anyone who disagrees with me is
invited to read Rombauer and Becker (my edition is 1975) and see how they
handle the problem. Here, from the EGGS entry:
EGGS AND EGG DISHES
...
whites, to fold, 545, 665, 665
whites, stiff but not dry, 545
whites, uncooked, about, 743
yolk, to add to hot liquid, 543
yolks as sauce thickener, 339

- Avoid making an entry for a term used in passing or in the negative. For
example, a paragraph with the phrase, "... beets, unlike artichokes, ..."
requires an entry for beets, but probably not for artichokes.

- Watch out for homographs--two words that look identical but are used in
totally unrelated senses and often have different pronunciations. For
example, the index entry for Lead (the chemical element--and no, I don't
use it in cooking) should never point to the portion of the text that quotes
the hymn, "Lead, Kindly Light." An "automatic" indexing tool could easily
give you this kind of error.

- Try to avoid triteness. Here's an example based on something I actually
saw:
USING
Compiler, 75
Editor Program, 34
Linker, 92
This is a silly entry. Nobody will look up "Using." Its inclusion makes
the indexer (and the author) look stupid. If you cannot avoid silliness,
put in these three entries, devised decades ago by a wise-guy friend:
Circular Argument, see Petitio Principii
...
Petitio Principii, see Proof by Assumption
...
Proof by Assumption, see Circular Argument

Best of luck on creating a good index. It's not hard, but it does require
careful thought.


On Mon, 22 Sep 2003 18:14:44 +0530, Nilesh Parmar <nilesh -at- pramati -dot- com> wrote:


Hi,
I've just subscribed to this list and found it very active. I'm learning
loads of things. Thanks a lot!!. I would like your valuable suggestions
regarding best practices that one should have in mind while indexing a
document.

I have a manual that needs to be indexed. I haven't indexed a document
before. I'm using Frame Maker 7.0 and know how to index words but would like
inputs as to what to look for while indexing a word. How do i index related
words togather. What are good practices, what are things we should avoid
etc.,

Thanks in advance,
Nilesh


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

NEED TO PUBLISH YOUR FRAMEMAKER CONTENT ONLINE?
“Mustang” (code name) is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to Web, intranets, and online Help.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! See a live demo that
will take your breath away: http://www.ehelp.com/techwr-l3

---
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.



Follow-Ups:

References:
Leaving: From: Tamara Reyes-Muralles
Indexing- Best Practices: From: Nilesh Parmar

Previous by Author: Re: Marketing Yourself
Next by Author: Re: Tech Writing Skills, College Degrees, Marketable Skills
Previous by Thread: Re: Indexing- Best Practices
Next by Thread: Re: Indexing- Best Practices


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


Sponsored Ads