RE: To Index or not to Index

["Jones, Donna" <DJones -at- zebra -dot- com>]

I sent this message directly to Dan so I wouldn't sound like a know-it-all
to everyone on the list. However, from his positive reaction to it, I got
the feeling that it isn't a bad thing to send the message to the list in
general. Maybe others who are new to indexing will find some of the advice
helpful.

As I told Dan in my reply to him, if you would like to see one of my
indexes, please go to our web site: http://www.zebra.com/SS/manuals.htm

Click on the XiIII Plus User Guide (you'll have to fill out a registration
to get to the PDF). That manual includes and index that I did recently, and
it's fairly detailed. You'll see most of what I mentioned in the list below
in action there. (I didn't write most of this particular manual, but I did
redo the index.) Looking back at this index, I see that I violated some of
my own rules a time or two, but at least most of it follows...

Cheers!
Donna


 -----Original Message-----
From: 	Jones, Donna  
Sent:	Tuesday, May 04, 2004 2:28 PM
To:	'dan -dot- gallagher -at- pulsartech -dot- com'
Subject:	RE: To Index or not to Index

Hi Dan,

When I use just about any sort of reference book, I turn to the index to
find what I'm looking for. I don't want to have to hunt for things by paging
through the book or wading through the TOC. I want it spelled out where
everything is (picky, ain't I?). Nothing is more annoying than knowing that
something I need is in a book but not being able to find it.

That being said--as a writer, I love indexing because it helps make my
documents more usable. I don't consider my work complete until it has been
properly indexed. Fortunately, because of my years of experience in creating
them, I can whip out a fairly complex index in a relatively short time. It
can be difficult to index an existing manual, particularly if you didn't
write it, but it can be done. Just like any other skill, indexing is
something that you can learn and learn to do well. 

Here are some pointers to help you if you find yourself doing an index for
the first time. I'm sure there are articles and documents out there that
will give different instructions, but this is the method I use, and it
always seems to work for me. There are no hard and fast rules for how long
an index should be or how long it should take you to do one. All of that
depends on the content of the particular document that you're working on. I
could have a 50-page document with lots of technical information and short
procedures that warrants a 10-page index and a 200-page document with long
procedures that warrants only a 6-page index.

Depending on how much time I have to do an index, here is how I determine
what to cover:
*	To create a simple, quick-and-dirty index, just index the headings
and group what you can under obvious terms.
*	To add a level of complexity, add alternative terms for the headings
and go into more detail so more things can be grouped under assorted terms.
*	To go in really deep, add in just about every way you can think of
to access each relevant piece of information. Ask yourself, "If I were
trying to look up this section, what things might I look under in the
index?"

Then there are the finer points to creating an index:
*	Group things that start with the same word or term under the same
level-one entry whenever possible. For example, "sensor adjustment" and
"sensor selection" could be changed to the level-one entry "sensor" with the
other two terms indented below it as level-two entries.
*	Try to avoid multiple page numbers under each index entry. The last
thing users want to do is to play hit-or-miss to find what they're looking
for. Give enough detail for each entry to be unique (the challenge is to
keep it brief). For example, rather than "sensors, 34, 52" try
"sensors:adjustment 34" and "sensors:selection 52" (the colon indicates
where you go from level-one to level-two).
*	It's okay to go to three levels of index entries when necessary
(entry:sub-entry:sub-sub-entry), but don't go deeper than that.
*	Keep sub-entries with the corresponding higher-level entries unless
you absolutely have to split them up for spacing reasons. If it's not
possible to keep them together, repeat the higher-level entry at the top of
the column or page where the topic is split. This will keep your users from
getting lost. (The FrameMaker User Guide index is a prime example. Flip to
the middle of it and start reading at the top of a column or page, and you
won't immediately know what topic you're under.)
*	Try not to group everything under a handful of level-one entries.
For example, if all of your index entries fall as level-two entries under
the term "routine procedures" because you're writing a maintenance manual,
you probably don't need to use that term.
*	If you find yourself doing a lot of "ABC. See Apple Butter Churn,"
you'd be better off listing the acronyms in a glossary or a list of
acronyms. Alternately, you can make "Apple Butter Churn (ABC)" your
level-one entry and list related topics under it. That way, someone who's
looking for the acronym would be able to find it along with the term and the
related sub-entries.
*	Rather than indexing every acronym, term, task, and concept, index
only those that the user is likely to ever look up. I don't need to know
where every mention of the term ABC is or every time I'm instructed to do
the same repetitive task (in my documents, this could mean repeatedly
indexing the procedure for accessing the front panel LCD parameters). Be
thorough, but don't overkill.

If you wind up doing indexing and can use some specific advice on-the-fly,
I'd be happy to help. Good luck!

Donna

-------------------------------
Donna L. Jones
Technical Writer II
Zebra Technologies Corp.



- CONFIDENTIAL - 
This email and any files transmitted with it are confidential, and may also
be legally privileged. If you are not the intended recipient, you may not
review, use, copy, or distribute this message. If you receive this email in
error, please notify the sender immediately by reply email and then delete
this email.


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

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo 

>From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.
http://www.doctohelp.com

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.