So, you have written the perfect help guide. You have addressed and held your audience with concise, relevant documentation written in Plain English. Now you must build an index to ensure that users can find the help they need.
Indexing is not every technical author’s favourite task, but it is one of the most important.
Traditional indexing today
With traditional user guides we scan the table of contents or flick to the back pages and look up a term in the index. Today, users can look for the help they need using a wide variety of formats and expect to find information quickly and easily. To ensure that user expectations are met, an index is as important today as it has always been. However, the index has evolved with today’s technical authoring tools.
Index vs search functions
It is tempting to allow users to rely on search tools when building web based help. The search tools in web based help are very useful but only offer part of the solution. Search tools scan your document for keywords but if concepts and related terms are not used within the documentation then users may fail to find the information they need.
One of the key skills in building an index is to include concepts and related terms. For example, you are scanning your cookery book shelves looking for inspiration. The plan is to bake some tasty treats for the weekend. Flicking to the back of the latest Mary Berry tome you completely miss the recipe for Jaffa cakes in ‘C’ for ‘cakes’ because you were looking under ‘B’ for ‘biscuits’! Now, you do not want to be drawn into an argument over whether Jaffa cakes are a cake or a biscuit (courts ruled in 1991 that they are a cake) but, when looking for recipes for biscuits, it might be nice to be introduced to the idea of Jaffa cakes. Incidently, Jaffa cakes could also be listed under ‘cookies’.
There are no short cuts with indexing
Automated indexing tools, such as the Smart Index Wizard in Robohelp 11, are useful but only do some of the work for you. Using the baking example, the Jaffa cake recipe would only be listed under ‘cakes’ if an automated index is used. Robohelp’s indexing tools do have the option of including synonyms and antonyms, but your choice of keywords must be approved manually. The indexer would have to have the foresight to list Jaffa cakes under ‘cakes’, ‘biscuits’ and ‘cookies’.
Indexing for wikis
I have been producing a lot of documentation in wiki form recently. Automated index tools seem to be standard but they are not fool proof.
With Atlassian’s Confluence Wiki, I have found a combination of both the Page Index Macro and the use of labels works well. This allows users to search for key terms and related terms using either the index or the search function.
So it would appear, like most things, you only get out what you put in. Now get on and index, it’ll be worth it when you find the recipe for Jaffa cakes!