Latest posts by techwriter (see all)
- BOOK REVIEW: “Design for How People Learn” by Julie Dirksen - July 10, 2017
- 12 Top Characteristics of a Good Technical Writer - July 3, 2017
- What Are the Qualities of a Good Technical Writer? - June 28, 2017
A quick technical writing quiz for technical writers:
Question – what is the most important part of any technical manual?
Answer – would you believe it is the INDEX?
Because I do not know of a single technical document user who would not immediately flip over to the Index and start searching for the words and terms of interest.
And the sense of frustration and disappointment is very real when the user cannot find an Index at the back.
In the technical documentation competitions that I’ve participated as a juror, a technical manual without an Index always created on us jurors an impression inferior to a similar manual with a well-developed Index. It’s always a value-added, an advantage, and never a disadvantage.
You need to provide an index and do it well if you are writing a manual over 30 or 40 pages long.
So how do you do it? What are the tricks of the trade?
First off, make sure you understand the important difference between a TOC (Table of Contents) and an Index.
A TOC presents topics in same the linear order that a reader encounters them in the book. It’s a summary (and a useful one at that) of “what comes after which topic.”
An Index, on the other hand, is an ALPHABETICAL list of the IMPORTANT TERMS and CONCEPTS covered by the manual, regardless of their location within the manual.
Thus without really understanding what the manual is about, you cannot write an Index because you would not be able to determine what is important and relevant from a reader’s (or end user’s) point of view.
That’s the reason why there are many professional indexers with their own organizations who create indexes as a lucrative full-time profession There are no professional TOC-creators, however, since it is a mechanical compilation that is usually accomplished at the click of a “Create TOC” button.
Here are some tips to help you compile great Indexes for your technical documents:
1) Always use lower case for your Index entries. “password” instead of “Passwords”, or “boat” instead of “Boat”. Lower-case letters are easier to read in an Index than the upper-case letters.
EXCEPTION to the rule: all Proper Nouns should start with a capital letter. “Africa” instead of “africa”, or “Toyota” instead of “toyota”.
2) Always use singular case for your Index entries. “fuse” instead of “fuses”, or “capacitor” instead of “capacitors”.
3) Do not have more than 3 levels of nesting. Human mind starts losing track beyond 3 levels. Easy-to-read Indexes do not have more than 3 levels of indentation.
4) Do not use verbs for Index entries.
If possible, all your entries should be singular nouns.
If, for example, you’d like to point the reader to the page where “adding a network” is explained, create a first-level index entry “network”; then insert an indented second-level entry under it, named “adding”.
Why? Because most people would not search for “adding” as an abstract activity in itself but only in its relationship to another concrete object, like “network”. So it’s better practice to anchor the verb “adding” to the noun “network” then other way around.
5) If you use an acronym as an entry, always create a cross reference to its open form and then give the corresponding page number at the open entry.
For example, your entry for MPG should be “MPG, see miles per gallon”. And then: “miles per gallon … p. 17” (just an example). Otherwise you run the risk of confounding your readers by an unexplained acronym the significance of which remains a mystery until the reader visits that page and does further research into it.
If, on the other hand, you explain the acronym’s meaning in the Index, the reader will be saved that research and will develop more trust both in your Index and in your document.
May your work take you to the happiness and prosperity you deserve like a well-written Index!