The index is one of the most valuable—and most popular—features of software documentation because it can lead users to exactly the right information. This chapter covers index methodology: how to decide what to index, levels of detail, phrasing, building, and proofreading.
Plan Your Indexing Strategy
There are two methods for creating an index: manual, in which you make notes as you read through a document, or electronic, in which a software indexing feature identifies terms.
Manual Indexes
To create a manual index, the document must be essentially complete so that page numbers are correct. The steps are as follows:
¨ Review the user analysis to remind yourself of how the software will be used
¨ Read or scan the page for index entries (main topics, concepts, and tasks; tables, figures, captions, examples, definitions, acronyms, and abbreviations; or menu names, tool buttons, and keyboard shortcuts)
¨ Record all index entry locations in a word processing file
¨ Alphabetize, edit, and format the index for consistency and usefulness
Electronic Indexes
An embedded indexing function is part of most word processing software programs.
These allow you to highlight terms and assign them to categories. It’s possible to index as you create the document, and then compile the index when it’s finished. Advantages to this method include automatic alphabetizing, automatic formatting, and easy revisions. The process is similar in some ways to manual indexing:
¨ Review the user analysis, keeping this in mind as you create the document
¨ Mark index entries as you write or edit
¨ Build the index: select the location and use the software to create the index
¨ Edit the index to eliminate inconsistencies, double entries, missing entries, etc. (Note: corrections must be made in the text, not the index.) Format, if necessary.
Decide What to Index
Try to make your index “support the activities and actions the user will undertake in applying the program to workplace needs.” Have developers, users, and other writers review the index specifications. Consider commands and functions (menu terms), concepts related to subject matter, user synonyms for program terms and proper names, user questions, glossary terms, and tasks and procedures.
Identify the Level of Detail
A very simple one-level index organizes the table of contents alphabetically. A standard two-level index includes main headings (categories), subheadings, and locator numbers. Three or more levels are very complex. An index may also be described by the number of “indexable” items per page of the document: a light index has 2-3 items, a medium one has 5-7, and a heavy index has 8-9 items per page.
Decide on Phrasing and Format
Writers need to plan the phrasing and formatting of index entries. Cue the primary locator numbers by bolding, capitalize terms consistently, make entries sound like sentences, and cue special terms.
Edit and Proofread
Carefully edit and proofread the completed index for mistakes such as indentation errors or inaccurate page numbers. Ask a user to review and test the index, if possible. Consider what content to emphasize and how to group information.
Discussion
Because indexing is often left until the end of a project, indexers may feel pressured to finish quickly because of publication deadlines. However, an index accesses the document from the user’s point of view and directs the user to the information they need. It is useful to beginners and advanced users alike.
A print index, located at the back of a manual, contains terms printed alphabetically in a two- or three-column format. An online index lists terms alphabetically and allows users to either scroll through the list or click on a letter from an alphabet display. A keyword search allows users to select a word from a list or enter one manually; a search engine then matches it to related topics. The writer is responsible for creating the electronic links. This type of search is often more limited than other types of indexes.
Microsoft Word, Adobe Framemaker, and other software programs have indexing capabilities. Some programs also work with HTML files. Problems occur when search engines retrieve too much irrelevant information to be useful, because they examine the entire text or web page. “Meta” tags can be used to locate certain responses identified by the web designer. However, information retrieval is complicated by partial words or misspellings.
Indexers rely on reference resources such as dictionaries, thesauri, encyclopedias, fact books, phone directories, organizational listings, geographical maps, and other collections of information (for example, science, medicine, business, law, agriculture, or computer terminology). As Barker notes, “These kinds of resources can help the indexer make the crucial matches between the vocabularies of a software program (represented by the words that make up the interface) and the terminology used by and familiar to the user.”
13 comments:
Nice job on this summary! I know that as a technical writer, I am glad that documentation software programs allow writers to index while writing. That was one thing with Author-It that I really liked. Previously, I'd used FrameMaker, and I think there were times that I would have to go through and have my own terms defined for the Index.
Nice work!
Indexing is one of those jobs that I've been told is "best left to a professional." This underscores the vital importance of a good index to users--it's often the first and only place they'll look when they're trying to find something (in print documentation, anyway). I've had people ask me if I would index for them, and I told them no because I wanted them to find someone who was trained in indexing. Frankly, I'm a little scared to index at this point because if I mess it up it has major repercussions to the usability of the work!
I agree with David. I have so little experience with indexing, so the process intimidates me. That's why I appreciate the depth of this chapter. I still don't think I'd feel comfortable with indexing, not without a lot help, such as the function in AuthorIt (but even that was still tough for me to figure out). At least now I feel like I understand some of the logic behind indexing.
The only time I've ever produced an index is on my documentation project with Author-It. I can't imagine producing an index manually. That could be a huge job. I am in the middle of editing a science textbook at work right now, and I just got to the index where my manager asked me to verify page numbers. I know it is important, but it is obviously a very tedious boring job, so I'm having a hard time staying focused on it. I have a lot more respect for indexers now!
Barker brought up good points on indexing. There is an indexing feature in MS Word; I haven't used it yet. It didn't look like it was real promising, so I index the old fashioned way. It's more tedious to have to recheck page numbers everytime you add something to the document, but it has to be done.
Dr. Nord told us in the copy-editing class that indexers (yes, tehre is such a profession) make a fair amount of money if they are good at what they do. In order to be good at it, I imagine you have to enjoy doing it, so if you are highly organized and enjoy indexing, maybe being an indexer is the perfect job opportunity!
A good summary on an important topic. I did not realize there was this much to indexing a book or manual. I personally have never indexed a document, and have a new-found respect for the people who do it. It's the kind of task you would really have to have passion for as it is not exactly creatively challenging.
Thanks for the good summary.
A good summary on an important topic. I did not realize there was this much to indexing a book or manual. I personally have never indexed a document, and have a new-found respect for the people who do it. It's the kind of task you would really have to have passion for as it is not exactly creatively challenging.
Thanks for the good summary.
A badly produced index is indeed a frustration. I agree with David--if your index is messed up you most likely will lose the trust of the user. Having said that, I'd like to take a crack at indexing sometime. I like to seclude myself in a room and concentrate and this type of work would lend itself to that scenario quite easily.
Even thou the job of indexer sound tedious, I enjoyed reading this chapter. It was interesting to find what goes behind the indexing process. Before reading this I always wondered about how do indexers decide what to index- now I know- it is user driver, of course! I gained new perspective and appreciation for indexers job.
I thought this was a useful and interesting discussion of the process of indexing, especially for those who have little or no experience with it, but who may be induced to work with one. I also appreciated the discussion of softwares used because it made the information a little more applicable.
The chapter indeed brings up the importance of indexing and its difficulties. I am actually someone who would have no problem being hired to perform index writing. First off, I think it is crucial that the indexer be with the project from the start, or at least close to the start. Indexers have to be knowledgeable of the material just like the writers, as knowledge of the material tends to highlight important terms/features.
I've had experience with HTML meta tagging, and I find it exciting and interesting. One thing to be aware of is that improper meta tagging can lead to your website being banned from search engines such as Google and Yahoo! For example, a lot of pornography sites will place thousands of words in their meta tag index in order to appear near the top of search results. If the content described in the tag does not match that of the web page/site, then that site will often be removed completely from future searches. I highly respect this practice as it attempts to rid searches of "spam." This is also an example of how indexers are incredibly important and a lot of what they do can have serious repercussions.
I have no problem with indexing, and I would love to have the opportunity to do more of it in the future.
This chapter also intimated me. As others have noted, I was in Dr. Nord’s editing class where he briefly discussed indexing. It seems like such a huge task that really needs to be completed by a professional who knows exactly what they are doing. There are so many bad indexes out there and I would not want to be the person responsible for one of them! I would though like to learn more about how to create indexes and more information about them though… perhaps an upcoming class?
Post a Comment