Posts Tagged ‘indexing’

How to write an index

Posted in For new technical writers on March 9th, 2011 by Jenny – 5 Comments

new zealand (239)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