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:question on indexing From:Ken Schumacher <ken -at- VENUS -dot- ODETICS -dot- COM> Date:Fri, 16 Apr 1993 14:09:22 PDT
Matt Hicks <matt -at- UNIDATA -dot- UCAR -dot- EDU> writes:
>So what are your thoughts on the need for sublistings?
A few thoughts...
I'm indexing the latest revision of a 300 page operator's manual,
and am having to live with my mistakes. I admire your desire to
have the index be comprehensive, but BE CAREFUL. Indexing too
much is the mistake almost everyone makes when they begin p
racticing that black art. A complete index CAN be succinct.
If you have to revise your document later, because of some
change in the software, the usually trivial task of making a
couple changes can balloon into a nightmare of redoing index
headings, and sub-headings, and sub-sub-headings if the original
index is not organized well.
For example, the machine I document is "modal", with Play Mode,
Data Base Mode, etc. used for different, interrelated tasks. I
made the mistake of creating "meta" level descriptions, and then
indexing sub levels, like
Play Mode
Playlist
Editing a playlist xx
Playing on-air xx
Then the software changed, so you can edit different portions
of a playlist in different ways, and you can edit playlists in
Editlog Mode, and you can edit events in Data Base Mode, and
what you edit in one mode affects other modes, and now I'm
faced with (only a slight exaggeration)...
Play Mode
Playlist
Editing active events xx
Editing inactive events xx
Data Base Mode
Editing events
Effect on Play Mode xx
Effect on Editlog Mode xx
Now, I also believe the index should reference things in different
ways, and so I need multiple index entries for the same text.
So now I have...
Playlist
Editing
in Play Mode xx
in Editlog Mode xx
and...
Editing
in Data Base Mode xx
in Play Mode
active events xx
inactive events xx
etc. etc. etc.
No, this is not fun, and I'm now trying to simplify, simplify,
simplify and still have the index be effective.
|---------------------| |
| ken -at- odetics -dot- com | "...let the words be yours, |
| (Ken Schumacher) | I'm done with mine." |
|---------------------| |
