Appropriate content for index?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Lisa Wright is creating <<... a user/training guide for a new module in a
suite of software. One other module has already been documented. In the
existing guide, the writer indexed what I would call "meta data" about the
guide itself, including listing entries such as: "bold text" (a doc
convention) "getting started" (a doc section) "user guide conventions" (a
doc section)>>

A bit unusual, but no reason not to put it there. I don't think I'd
personally include such things, but they can't hurt and could possibly help.
Including them is more of a problem if the indexer is doing so at the
expense of other, more important things (e.g., synonyms and
cross-references).

<<All the training and experience I've had on creating indexes says that the
index should *not* be a recreation of the TOC>>

Although that's true in principle because an index is not a table of
contents (TOC), it's obviously incorrect in practice: the index must also
include every entry in the table of contents. Why? Consider the example of a
really, really long book, with a TOC that runs to a dozen pages. I want to
install a specific subcomponent of the software, which appears towards the
end of the TOC, two levels down the heading hierarchy, under "installing
component x". I can either read 11 pages to reach this entry (and hope that
I'm not skimming so fast that I miss it), or I can open the index directly
to "installing" and look for "component x". The search time may be
comparable for both approaches, but I'm far less likely to miss this entry
if I consult the index. Moreover, TOCs often use words that aren't a
reader's first choice in searching, and a hurried reader may miss an entry
in the table of contents; in the index, the reader has one chance to find
the section for each keyword synonym you use, rather than a single chance
(as in the TOC).

<<I had to look at the content to determine what was application-specific
and what was document-specific.>>

That's a clear sign that even if the indexer's _approach_ is defensible, the
results aren't. Probably what's required is a different type of index entry
(e.g., "About this manual", with subheadings for "use of bold" etc., or
"bold, use of in this manual"). Or just drop the metadata if you really feel
it adds nothing. But first look at the information carefully to see whether
you can find a good way to include it that will help the reader.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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