Writing an index for your technical documents can be an intimidating task for a new technical writer.
In fact, often we don’t include indexes in online help now, instead relying on the search function. But for some audiences, and obviously for printed documentation, a good index is invaluable.
For example, one system I document is an enterprise application. It includes hundreds of code tables, containing codes for customizing which fields are displayed on the screen, which types of invoices and other documents can be printed or emailed, and which users can access the various parts of the system. When you look for help about a code table, you can either search for it by name, or if you don’t remember the exact name, you can browse through the index, looking for, say, all the code tables that start with “F0”. Without the index, it would be more difficult to find the information you need.
I was reminded of how much I rely on indexes and search when I bought my first ebook last year – a guide to CSS. I was super excited that the book was available in Kindle format, because I thought I’d be able to quickly search for information. In fact, I thought the ebook was the answer to clearing my bookshelves, the ones currently filled with doorstop reference books. Imagine my chagrin when I discovered that the Kindle for PC program didn’t include a search, and that the book’s index was just a list of words, no links and no page numbers! I was so annoyed, I did something I rarely do – I emailed feedback to the Kindle for PC team expressing my dismay. Fortunately the program has since been updated and now includes a search.
In a perfect world, the best thing to do if you need to create an index, is to hire an indexer, someone who makes a living writing indexes. A good indexer loves nothing more than the puzzle of creating a comprehensive and well-constructed index. But often there isn’t the time or budget to hire someone, and you, as a technical writer, are expected to create one yourself. If it’s your first time writing an index, here are some suggestions to help you get started.
1. Start with your topic headings.
Add one or more index entries for each topic heading. Don’t forget to consider capitalization. As a general rule, use lower-case, except for proper nouns. This is a good first pass through your document.
2. Consider other words that users might look for to find these topics.
Go through the topic headings a second time and consider other words that a user might use to find the topic. For example, if the topic is about restarting the computer, you might add another entry under “reboot” for users that know that term.
3. Look for keywords in each topic.
Look through each topic to find keywords that a user might search for. These might include the names of dialog boxes or windows, or unfamiliar terms, for topics that include a definition of the term.
4. Think of synonyms for the keywords.
Find synonyms for the keywords you identified in the previous round. Consider your audience and terms they might be more familiar with.
5. Brainstorm other words users might look for.
Think of the product you have documented and brainstorm any other words a user might search for.
6. Read the completed index.
As with all your writing, be sure to read through the completed index, carefully checking for spelling errors and typos.
What about you? Any suggestions for first time indexers?
If you liked this post, consider subscribing to my RSS feed. Or have posts delivered via email. Thanks for visiting!
Photo via Flickr user Svetlana Zhukova
5 thoughts on “How to write an index”
Indexing is a critical skill. It requires one to be meticulous and to put oneself into the minds of users who think differently. An index should be considered a reference on its own. It should be imaginatively created and then ruthlessly edited until it is complete and well-formed.
I always begin with a three level (entry, sub-entry, sub-sub-entry) index on my own work. (I also index as I go, warming up to a new day of writing by indexing what I wrote the day before.) Beginners and those wholly unfamiliar with the work may end up using four levels. This makes it easier to see patterns in both information and thought. For those who feel positively intimidated, I suggest looking at the text by subject, verb and object to develop a rhythm of thought. Make sure every definition and every explanation of a concept has an entry. (Sometimes keywords aren’t as useful as they seem, pointing to what amounts to be a mention.) Verbs, more precisely, gerunds, are appreciated. I don’t suggest “entering,” followed by every field name, but if a user is tasked with, for example, managing an account profile that requires actions that don’t appear together in the manual, the entries “managing accounts” and “accounts, managing,” followed by sub-entries, will point them to the correct pages. (Keep in mind this may be the only training they get.) If a main entry is followed by nothing but a string of page numbers (more than three) it requires sub-entries. Eliminate “see” entries; they’re a useless annoyance. Even if your intent is to educate the reader on correct or preferred terminology, let the reader learn that once on the page. If the entry is important enough for a “see,” it’s important enough for a page number.
Finally, professional indexers are indeed expensive; however, The American Society for Indexing (asindexing.org) has references available for an individual membership price of $150. Transferring the knowledge necessary for one or more co-workers to construct a very good index should be easy. I’ve been doing so for more than 15 years, and while I’m always the final person to review indexes for online help and manuals, I think those I’ve taught do a fine job and our users truly appreciate our efforts.
Thanks for your comment Laurie!
I think I only go to two levels myself, but I can see from your examples how you’d use three levels. And I agree about the “see” entries. I prefer things to be simple.
Do you index online help and printed documents in the same way? I tend to index online help as I go, but for printed documents I prefer to leave it until the end.
This is a nice article. Thanks for the tips!
thank you Jenny Watson, it’s a very helpful article for them who wants to make their freelancing career in the writing field.ï»¿