Dallas-Fort-Worth (DFW) Texas based Brandfocal provides Technical Writing services.
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.
Choosing which instances to mark
The words “error handling” might appear three times in every paragraph within the error handling section. You don’t want to include separate index entries for each instance – that would be overkill and lead to a cluttered, difficult-to-use index. If your indexing supports page ranges, you could decide to include the entire range of the chapter within a single index entry. If your index only allows single page entries, then you’ll need to determine if marking the first page of the section is sufficient or if you need further markers at important points within the section.
Perhaps a more complex situation is when you discuss a concept in a chapter overview and then provide full details a page or two later within the chapter. You’ll need to decide whether it makes sense to index both places or just the area where you provide the detail. This is your choice, and you’ll need to decide what makes sense for your book.
Build in redundancy
Once you’ve chosen the topics and terms to index, you might think you’re almost done with your index. You would be wrong. Not every reader thinks the same way and simply including a single entry for an importance concept isn’t enough. If there are alternate terms, use them.
For instance, in the Visual Basic chapter, include the common abbreviation for Visual Basic – VB – in the index. Think of alternate terminology people might use when saying “developing clients” and provide index entries for them. Do the same for other words and phrases. If you don’t use that terminology at all within the book, use a “see” reference to indicate that it’s covered under another name.
We came up with five base index entries for the Visual Basic chapter above. Adding in redundant and alternate entries, we might get the following entries:
- Building Visual Basic Clients
- Clients, Visual Basic
- Clients, Visual Basic, Available Objects
- Clients, Visual Basic, Debugging
- Clients, Visual Basic, Error Handling
- Debugging, Visual Basic
- Developing Visual Basic Clients
- Error Handling, Visual Basic
- Exceptions: see Error Handling
- Objects, Visual Basic
- Throwing Exceptions: see Error Handling
- VB Clients: see Visual Basic Clients
- Visual Basic, Available Objects
- Visual Basic, Debugging
- Visual Basic, Error Handling
- Visual Basic Clients
As you can see, this gives the user many more ways to find that same information they need.
Consistency in indexes
Just as it’s important to be consistent throughout the text of the manual, it’s also important to provide consistent index entries. If you normally capitalize all words in an index entry, make sure you capitalize them in every single entry. If you generally include three variants on each object, make sure each variant is included for each object.
You’ll also want to be consistent regarding which occurrences of a word or phrase to include in the index. If your chapter has a general overview that briefly discusses each major topic then later sections on that discuss those topics in detail, either index both locations for every term or don’t index both for every term. Don’t index some of the words in the overview and some just in the detailed sections that follow.
When to build your index
Many people recommend doing all of your indexing at the end of the writing process. This is a holdover from the time when indexing had to be done by hand and the simple shift of a single page could invalidate most of your work to date. In these days of automatic indexing and markers that move with words as they shift locations, there really is no technical reason to index at the end of the process and many people choose to index as they write.
There are advantages and disadvantages to either choice. Indexing as you go definitely slows down the writing process, meaning it will take longer before you’re reading for editing and review. Many people find the resulting stop and go writing process prevents them from properly concentrating on what they’re writing and thus won’t index as they go. If you index at the end of a tight schedule, you can do your indexing while others are editing and reviewing your book, then give the editors your index once they hand back the rest of your book.
In my experience, leaving the indexing to the end of the writing process can lead to a very rushed and often inferior product. Most non-writers fail to understand the importance of a good index and it’s more difficult to get a product manager to give you more time to index a book than it is to get more time to write the last two chapters. On the other hand, indexing as you go is more likely to lead to inconsistencies as you could make different choices regarding capitalization or marker placement or other index features during different phases of the indexing. These problems should be caught during the editing process. If you index as you go, be sure that someone edits the final result with an eye toward consistency.
Another alternative is to index each chapter or major section after it’s finished. This allows you to write major chunks of text without constant interruption and still avoids the rush of trying to fully index a book when time is running out. It can still lead to some consistency problems, but again these should be caught during the editing process.