TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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:
*****************************
Genevieve:
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
Eric Thomas [erict -at- installshield -dot- com]
*************************************
Genevieve,
I did some looking a while back for similar information and found these
sites provided considerable help and insight into indexing.
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
Cheryl Magadieu [leftymagoo -at- attbi -dot- com]
******************************
Genevieve:
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)
(1996)
You can't go wrong with #1, for *MANY* reasons, and #2 focuses on the
issues
we face within the 'high-tech' industry. (I found #1 at my local
Half-Price Bookstore
in 'mint' condition.)
Hope this helps.
-JOHN
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). http://www.componentone.com/d2hlist1002
---
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.
