Barker – Chapter 14: Designing Indexes

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.”

Beyond Skill Building: Challenges Facing Technical Communication Teachers in the Computer Age

(By Stuart A. Selber, Originally printed in 1994)

Teachers of technical communication often focus on teaching their students computer technologies to help prepare students for future employment responsibilities. However, this focus on technical skills may be at the expense of “critical political and ethical understanding.” Critical and rhetorical skills and other humanistic issues should not be neglected.

Selber researched course descriptions from 39 colleges and universities offering technical communication programs to determine why and how computers were used in the classroom. His purpose was to identify areas of instruction that were “under-represented as well as identify concerns important to productive teaching about and with computers.”

As might be expected, there was a large variance in what was considered appropriate to include in the programs. While most basic tech comm classes had expectations that students would use word processing programs and print on laser printers, others were teaching “hypertext and hypermedia, (asking) students to work collaboratively online, (or requiring) them to join electronic conversations in their specialty areas for interaction with professional writers and editors in business and industry.”

Selber categorized the instructional goals of the technical communication courses and found that most courses focused on one of three objectives: “production; computer literacy; and situating technology in historical, political, and social contexts.”

Production Courses

Many of the courses focused on skill building and learning computer processes that would be of value in the workplace. They were further categorized as follows:

· Computer Applications Courses: hardware and software skills

· Document and Graphic Design Courses: skill-building in desktop publishing and graphic design programs

· Publications Management Courses: the nuts and bolts of producing technical publications, such as editing, layout and visual design principles, as well as scheduling and budgeting

· Specialized Writing Courses: focusing on a specific genre in technical communication such as proposal or report writing

· Introductory Writing Courses: introductory technical writing

Computer Literacy Classes

These courses attempted to teach about computer technologies as related to broader theories such as reading, writing, or even psychology. For example, a class dealing with visual design might incorporate topics such as the “human visual system” or “theories of perception and attention.”

Courses Situating Technology in Historical, Political, and Social Contexts

The purpose of this type of instruction was to transcend the “skill-based approach” in order to help students understand how technology shapes societal, historical, or political issues and how “implementing and using computer technologies are fundamentally ideological acts.”

Selber felt that teachers might be “reluctant to engage in a critical examination of our culture’s technological foundation.” Many explanations were given as to why computers were being incorporated into the curricula. Besides the common rationale that teaching technological skills would increase students’ marketability, other reasons given included the necessity of building required skills necessary for technical communication activities, improving students’ writing, and promoting collaboration.

By examining how computers were being used in the classroom, Selber hoped teachers would prepare students who were “literate and responsible users of computer technology.” He discussed three main challenges that teachers might consider when answering the question, “Why are computers used in our curricula?”

Challenge #1: Balancing Technological with Literacy and Humanistic Concerns

Although the most common reason cited for teaching technology was to help to prepare students for their future employment, Selber felt that if this was the main focus, teachers would lose sight of the literacy and humanistic issues that are also important. When planning programs and course offerings, he stressed the importance of balancing the different types of classes that are outlined above.

Challenge #2: Re-Envisioning our Computer-Related Curricula

He also felt that current programs and classes needed to be examined to determine if enough emphasis was being given to humanistic and literacy issues in teaching technology. Selber said that “too often we integrate computers in our classrooms without a critical rethinking of how they might inhibit our instructional goals.”

Challenge #3: Educating Teachers who Use Computers in Their Classrooms

He also encouraged faculty, staff, and graduate assistants to learn how to incorporate computers into the classroom. Selber found very little guidance for doing so, and he called this “shortsighted.” Because of the rapid changes in technology, he cautioned instructors to not only keep pace with the change, but to function as “technology critics and reformers” and to understand how to responsibly teach technology to their students.