This is part of the Help Authoring Tips series.
Indexing should be, in theory, one of the most important tasks you do as a technical writer. If we all agree that most people don’t read a manual from cover to cover (and certainly don’t read every help topic), then it follows that the index should play a critical role.
The index should point a user to the most likely topic or topics that would provide the information they seek (based on the keywords they chose). It should. It really should. But how often does it?
In practice, the help index is often ignored in place of using the Search functionality. Most people, if asked to explain the difference, can’t come up with an accurate and reasonable definition of either. I once had an engineer complain because the index was incomplete. When he finally explained what he was talking about, I understood that he thought my index would provide search functionality. Once I showed him the difference, he was thrilled and kept testing it. He was one of my favorite engineers – it was like a game to him to try to “outsmart” the index.
Following are some tips for developing a good help index:
- Don’t think from the documentation point of origin, think from the user’s point of view. Yes, this term is a good keyword for this topic – but is it a keyword that an ordinary user will consider? Too many people index by looking at what is there on the screen before them. What questions would this topic answer? What words or terms are in the heads of your users?
- Think in synonyms: God knows your users will! If you are documenting the Split window feature in Word, remember that some of your users are going to want to DIVIDE the window. Split is a Microsoft word and is fine for the name of the feature, but you are going to fail your users if you don’t consider other terms they might be using.
- Don’t over-index: This is true in all indexing projects (print and help). When you offer your users an abundance of possibilities, they sometimes choose none. Pick the single best topic for the keyword. If you can’t pick the top one, pick the top two. If you are sending a user to five different topics related to a keyword, there’s a really good chance between one and five, you’re going to lose your users. Each time users get to a topic that is not relevant, they consider giving up, backing off, searching for something else…or worse, not searching at all.
- Review your interface terms: Verify that you have included the most unique or unusual names within the index. A reference to the Cancel button might be useless and unused, but a reference to Propagate Alarms is going to help some users. Consider not just the window you have documented, but the workflows that might involve the use of this function.
- Remember to cross-post your index entries: Again, you need to anticipate how your users think – and the variations for each. By thinking your way “around the alphabet,” you will increase the access points to your information. For example, you should index CLI Parameters under both CLI and Parameters, or Editing a File under both Editing and File.
- Index both explicit and implicit terms: Explicit keywords are those that appear in the body of the topic; implicit are those that are implied but are not there. Often those that do not appear in the text of the documentation are as important (or more important) than those that do.
- Review your index before completing the project – verify that you don’t duplicate keywords (lookup table, lookup tables).
- A help index can have many more terms than a for-print index because while a user must physically scroll through a PDF file or turn a printed page, help users simply enter the first letter of the keyword and immediately “jump” past all the keywords that precede that letter.
- Don’t index the name of your product – this will waste space and potentially your user’s time. Everything in the help relates to your product; conversely, you should consider if a third party application or product SHOULD be in your documentation. If your application has a plug-in for Outlook, for example, than your user should be able to search for Outlook to find information about the plug-in.
The purpose of an index is to offer your users quick access to significant information in your help system. If the access is not quick (because they have to select numerous links or because keywords are unclear), the help gets a fail. If the information they finally get to is not significant and does not address their question, again, the help is a fail.
In a “perfect” document, the index would be the first and ideal place for a user to turn. As the author, it is your opinion that it leads to the best and most relevant information. The fact that users primarily go to Search before or instead of using the Index is an indication that we as help authors have a lot to consider when creating an index.