Technically Speaking: Tips, Techniques, and Targets to Make You a Better Writer
(As published in The Technical Writer magazine, articles by Hunter Brumfield)
If You Suffer from Index-Fatigitis,
There's a Cure — Part I
The index is, sorry to say, the forgotten child of the technical writing profession in Japan. Often it is simply abandoned. Elsetimes, it is a sadly neglected waif that fills the last few pages of a (typically) difficult-to-use manual. Rarely, someone makes the valiant effort and parents an index that is a legitimate and useful guide to the book's interior. To come across one of these gems is a pure delight, and a sure sign that the manual itself was similarly well crafted.
Four-hundred-member SWET (Japan Society for Writers, Editors, and Translators) and various individuals have tried to promote indexing as an essential part of most technical documents. SWET organized an excellent workshop on the subject some years back, in which some of Japan's few professional English-language indexers explained how to create a useful index.
In that workshop, as here, particular stress was placed on the word "useful."
A user manual is, by definition, supposed to be useful. It falls flat at the starting gate if it doesn't give the user a clear map to easily find his/her way around the pages. In fact, one of the key aspirations behind a well done technical manual is that the user will only have to read the parts that he or she absolutely requires. And how does he or she find those parts? Not the table of contents, which is only the roughest sort of non-alphabetized guide. The index is that all-important map.
If your eyes tend to glaze over at the thought that you might actually have to construct an index, then perhaps you are part of the problem. Or, to put it a bit more kindly, perhaps you're just another victim of that mind-numbing disease index-fatigitis that tends to infect writers somewhere near the end of a long writing trek. It is, in fact, a common illness for which I, as a previous sufferer, have devised my own cure.
The first important part of my cure starts with reading what other people have to say about indexing. The rest of the cure is doing an index making use of several techniques made possible by your computer. When you get finished I think you'll be amazed at your new skill ... and realize that it wasn't actually so difficult a job after all.
There are some excellent books devoted to indexing and various reference books that touch on it, offering sound advice and sensible guidelines. The most highly praised of the reference books is The Chicago Manual of Style, which approaches indexing in a delightfully fresh and readable way. This book describes the ideal indexer and the time pressure under which he or she must work this way:
"Whoever the indexer is, he or she should be intelligent, widely read, and well acquainted with publishing practices, also level-headed, patient, scrupulous in handling detail, and analytically minded. This rare bird must - while being intelligent, level-headed, patient, accurate, and analytical - work at top speed to meet an almost impossible deadline."
Even still, its editors stress, the index should not be overly rushed. "In addition to requiring intense intellectual concentration ... good indexing requires reflection, and reflection demands time."
• Ask yourself these questions
In an excellent paper on the subject in the journal Technical Communication, Susan I. Grodsky presented a series of questions you can ask yourself as you prepare to index your first (or next) document:
- What parts of the document will be indexed?
- How many indexes are required?
- What depth of indexing is required?
- What form of entry will be used?
- What form of locator will be used?
- How will cross-references be presented?
- What typographical style will be used?
- What alphabetization style will be followed?
Let's take the first three questions as a group. What is being asked here is, basically: how extensive do you intend to make the index?
The answer, of course, depends on the nature of the technical document and the type of user at which it is aimed. If the document is a user manual for a relatively sophisticated consumer product (a desktop computer, say), then you would want to be particularly thorough in your index. For instance, you must start with the assumption that the user is a novice who's unfamiliar with technical terms and jargon. This person will tend to conduct an index search much differently than an experienced user. Yet you must also assume both will use the index; therefore, in essence what you'd want to write is a combined index for both types of user. The expert is more likely to search for precise terminology, while the novice is more likely to search for actions. Both, of course will be similarly likely to look for key words. (See examples.)
On the other hand, if the document is highly technical and/or intended strictly for experts, then an alphabetized listing of instructions and key words may be adequate. If there is a great number of instructions, your reader might find it more helpful if you break up the index into several parts. A software manual, for instance, can have a general index and a separate one for specific actions.
The form of the entry and its locator (usually a page number) are the second key aspects of your index plan. There are two types of entries - the main entry and the subentry. You waste your time and especially the users if you compose an index of only main entries. Such an index is almost worse than no index at all - it presents the reader with a numbered maze that bounces him from one page to another until he finally reaches the information he desires. After the first attempts to use such an index, he'll generally give up in frustration. For instance. it is easy to see that
is far less helpful than
Now which would you rather use?
• Keep the index style consistent
Another important point to observe about index entries is that the main entries and subentries should follow the style throughout the document. For instance, if you wrote "Merging Files" as a section title, then you should index it either as "files, merging" or "merging files," but not "files, how to merge." Keeping the style consistent decreases confusion and makes it much easier for the reader to find the information.
Cross referencing, the next question to be considered, is a debatable issue. Virtually all academic books make free use of this indexing device. These "See so-and-so" references direct the reader to a different index location, either to a more extensive group of entries or to a similar subject area. For biographies, histories, and the rest of the academic shelf, they serve a good purpose. Nonetheless, in technical documents cross references usually are unnecessary. This is because they add a layer of depth to the index (and a burden to the indexer) that tends to make it less useful, not more. The user, as well, is better served by an entry that gives him the page reference straightaway, rather than jumping him to another part of the index.
Lastly, we come to the matters of typographical style and alphabetization. All indexes are set in what is called flush-and-hang style (also referred to as hanging indent). Within this style you can select between either "indented" or "run-in." Virtually all technical documents use the indented style, in which the main entry is given on the first line, and each subentry is indented and sits on its own line. With run-in style, semicolons are used to separate individual entries.
Indented style is both easier for the reader to scan and considerably easier for the indexer to construct, since it does away with all those nasty little semicolons. Run-in style also means you can't use the computer to alphabetically sort the items line-by-line for you.
As far as alphabetizing goes, I prefer to sort entries using the first letters of each indented line (letter-by-letter), and not of the main words (word-by-word). I use the first form partly because the rule is simpler, but mainly because that's the way the computer sorts the raw index. It's also the way people typically look up words, including in dictionaries.
As shown above, you should alphabetize subentries according to the first letters of the first important word.
Regardless of what style you adopt, it is essential that you be consistent and clear. Even slight deviation or confusion is an irritant to the user. If you irritate the user enough he'll stop turning to your index for help - which means it has failed the all-important test of usefulness.
• And now, the way you construct the index
There seems to be a time-honored way that one goes about actually making the index. Four different sources I consulted all seemed to have the same mostly manual method, which I will summarize here. In the next article. I'll explain how you can create your index more efficiently by taking advantage of your tireless microchip work companion. You'll actually use BOTH non-computerized and computerized methods, which nicely overlap.
The first strict instruction they all seem to give is that you should wait for the page proofs before beginning your index. That's so you can know for sure what pages the items will appear on.
When you finally can begin, you go through the manual with a marking pen, indicating main entries with one color and subentries with another color. As you go, you make notations in the margin about the entry, including what are referred to as "modifications." These modifications are what will later allow you to know how to refer to the referenced item. For instance, if you were to simply write "files" every time you happened on some bit of information on file handling, then all you would end up with in your index for "files" would be a practically useless series of page numbers.
The second step, the non-computer way, is making index cards. This requires that you go through your manual again, handwriting each entry onto a separate note card. These cards allow you to easily mix and match references. You're advised to lay them out on a large dinner table so they're easier to view and assemble. In Japan, a tatami floor does quite nicely. Each card has three bits of information on it: a heading, a modification, and a locator.
Be sure you always verify the page number. As The Chicago Manual of Style warns: "Once cards have been put in alphabetical order, it will be difficult or impossible to correct miscopied page numbers and such entries often have to be dropped from the index."
The third step is alphabetizing the cards, first grouping them into the 24 letters of the alphabet, and then further alphabetizing them within each letter group. Be sure to give yourself plenty of time for this. Alphabetizing the hundreds of entries of a large manual can be an enormous task, taking up both a lot of space and time.
This, of course, is where your computer steps in, which is explained in the next article.
Next comes the all-important step of editing the entries based on the style considerations mentioned earlier. As well, although you can't be expected to check the accuracy of all your page references, pick out a dozen or 50 cards and verify that they're still correct. Especially in a technical document, pages sometimes get added or deleted which can throw off your page references. It's always a good idea to check just to be sure.
Finally, it is necessary for you to input the index manuscript the typesetter will use for final page preparation. If you have used a computer, you can give him a copy of your file. This saves a lot of rekeying time, plus it greatly limits the chance for typographical errors.
And then (whew!) you're finished.
Copyright © The Technical Writer Magazine. All rights reserved.