Why software documentation needs index and how to make it work efficiently
Dennis CraneIt's a revealing thing, an author's index of his own work, - she informed me. It's a shameless exhibition - to the trained eye.
Kurt Vonnegut "Cat's cradle"
Index is not a brand new thing to people. You can find it in textbooks, encyclopedias, handbooks, manuals. Generally index is an alphabetically sorted list of words with page numbers (or hyperlinks to pages) where they are mentioned. The reason why end-user program documentation demands index is that it can be easily interpreted as ordinary book. People are used to presence of indexes in books, its convenience is proven. So why not include the same thing in technical documentation? Both types of indexes are intended to serve the same purpose. They provide users with a flexible alternative to the table of contents.
So how exactly does index work and what is the difference between traditional printed book index and documentation index? Traditional index is a list of single words or phrases in the end of book, containing one or several page numbers next to each item of the list. Electronic index is practically the same thing, but instead of page numbers there are hyperlinks to relevant sections of a document. Any index basically works with keywords. A reader thinks of words which might be connected to the topic and then looks through the index. If all or at least some of these words appear there, a reader can check pages listed next to keywords. It is the sure way to find some special information, if it is present in a document of course. That resembles how searching engines work - they index web-pages by extracting keywords, and when you submit a search request, they look through their index and produce search results.
That is why software documentation needs index which would ensure that user finds requested information if table of contents does not help.
If you are writing complicated end-user documentation, it will sure need index. In the same time this type of index is difficult to make. The main problem here is to pick the correct keywords and to group and sort them properly. Let me suggest some advice to help you arrange a plan I follow when creating index.
The hardest thing is to start it in the right way. Begin with looking through your topics and writing down keywords referring to them. The main problem here is people's associative thinking. When you start picking relevant keywords for a topic, you may forget to take into account keywords that some users recall when they search for this topic. However, the solution is not too complex. It just requires a little bit of imagination. Make your list considering needs of different types of users: newbies, middle-level and advanced ones. It is the basis of all your further work, so pay attention to this step. End-user documentation usability depends in a great way on how carefully you think over sets of keywords.
There are many tools for automated index creation, but even if you use those, I would highly recommend that you check and improve the results (by adding or deleting some of the keywords). It is preferably to have a built-in index creation tool in your help authoring system. One of such applications is Dr.Explain. You can easily add keywords here, create keyword structure and assign chosen keywords to topics.
When revising your work, allow for some time to pass to ensure freshness of vision.
After you made a good list of keywords and topics (and if you did it manually), invert your results. In the beginning it looked like "topic -> several keywords", in the end it should look like "keyword -> several topics". This way it will resemble book index and will be able to perform its main function. With Dr.Explain, your keywords are already arranged automatically. Regardless of topic you've picked in the topic structure manager, you will see the whole keyword list. To assign a keyword to the topic, just tick the checkbox next to it.
Unscramble index, create its topic structure. If you have a set of keywords which refer to subtopics of one topic, you can merge them. For example, you have words "hammer, shovel, drill", so you gather them under the word "tools" (the way you do it depends on you help authoring tool). Next time user types "tools", he or she will get the whole list. This option is also available in Dr.Explain.
If there are several technical writers working on the same documentation, for better results team members should swap tasks. Show your index to another technical writer so your colleague could check or supplement your piece of work.
Note that if you will try to create an index for a small simple help user manual without complex structure of topics, you will soon notice that it is practically the same thing as table of contents. In this case writing an index would be a waste of time because it duplicates table of contents.
These were just the basics. Details depend on specific documentation. Compiling an index is a creative task. It significantly differs from making a table of contents.
Article Source: http://www.drexplain.com
You are permitted to reprint this text as long as it includes copyright notice and direct link to our web site.