Lesson 6: Indexing Your Documents
It's your job to analyze everything the user needs to do to successfully use a product and determine the order they need to do those items. Then you need to determine what the user is likely to already know and make sure that you provide every other scrap of needed information. In addition you must analyze how someone who doesn't understand the product as well as you do would think about the product and provide logical entry points to the necessary material given those expectations. It doesn't help to provide every scrap of information your users need if they can't find that information within your document.
Indexing is an important but often overlooked step in this process. Most users are going to either turn directly to your table of contents or turn directly to your index and start looking for the material they think they need. You need to make sure that information can be found from either method even if the user doesn't yet know precise terminology or an exact word to look up. Cross-indexing is an art, one that eludes many otherwise very competent technical writers. Indexing is a skill that needs to be developed and practiced regularly.
Deciding what to index
It can be very difficult to decide which words to index. You don't want or need to build a complete listing of every word in your manual yet at the same time you want to make all of the important information within easy to find for every person reading the book.
A good place to start is with section headings. If an idea is important enough to merit a section heading it's probably important enough to merit an index entry. A chapter discussing building clients in Visual Basic might cover topics such as the available objects, error handling, and debugging. The first pass at indexing that chapter might include the following entries:
- Debugging in Visual Basic
- Developing Visual Basic Clients
- Error Handling in Visual Basic
- Objects in Visual Basic
- Visual Basic Clients
That's certainly a start, but those five entries aren't going to effectively lead people to everything they need to know about developing client applications in Visual Basic. That will probably be enough to lead any user to the general section on Visual Basic, but a user looking for information on a particular object may not think to look under Visual Basic. After integrating major headings, the next step is to look at the information covered by each and determine which pieces of information users are most likely to specifically seek out by name.
Most likely users will want specific information on individual objects. If the chapter discusses four objects - OurFactory, OurBean, OurStream, and OurText - then those should each be indexed as well. Basically during the indexing process you should return to your audience analysis and really think about what users will want to do with the information you provide and the background they bring to the table that will lead to the terminology they use to look for that information.
