An index is often a reader’s primary information retrieval device. When readers search for a particular topic and find it referenced in an index, they are assured that the topic is covered in the document and their search has ended. When readers do not find a topic in an index, they might decide that the topic is not covered in that document and they might look elsewhere.
This chapter discusses the following topics:
“What Is an Index?” on page 241
“Style and Format” on page 242
“Creating an Index” on page 245
“Refining and Checking an Index” on page 263
“Checking the Size of the Index” on page 269
“Global Index” on page 269
“Online Index” on page 271
According to The Chicago Manual of Style:
A good index records every pertinent statement made within the body of the text. The subject matter and purpose of the book determine which statements are pertinent and which peripheral. An index should be considerably more than an expanded, alphabetical table of contents. It should also be something other than a concordance of words and phrases.[1]
The following figure shows two examples of the indented indexing style. One example shows the index format for unnumbered chapters, the other example is for numbered chapters. The only differences between the two examples are the format of the page numbers and the use of “to” as a separator for page ranges in the book with numbered chapters.
Example 14-1. Index Formats
Unnumbered chapter format example: | Numbered chapter format example: |
---|---|
A application architecture, 12 application gateway, 211, 345–351 automounter facility
|
A application architecture, 1-2 application gateway, 4-18, 5-76 to 5-81 automounter facility
|
B backing up
|
B backing up
|
Many technical documents use up to three levels of nested entries: primary entry, secondary entry, and tertiary entry. Each entry level is indented from the previous level. These three levels appear as follows:
primary entry
secondary entry
tertiary entry
The primary entry is the principal subdivision of an index. A simple primary entry includes the entry and a page number. A primary entry covering two or more page numbers is usually divided into secondary entries. Each secondary entry must bear a logical relationship to the primary entry. A secondary entry covering several page numbers can be further divided into tertiary entries. Each tertiary entry must bear a logical relationship to the secondary entry.
In an indented style, each secondary entry and each tertiary entry begins a new indented line unless there is only one secondary entry. If an entry runs over the width of the column, it is indented in flush-and-hang style. That is, the first line is set flush and the rest of the entry is indented below it.
Least-Recently-Used (LRU) Ring functional
description, 3-17
elements of, 3-24
A comma and a space are inserted between the entry and the first page number. Subsequent page numbers are separated with a comma and a space. Page numbers appear in ascending order.
Do not include a page reference in the primary entry if it has two or more secondary entries.
functional description
input block, 2-3 to 2-32
introduction, 2-1
output block, 2-33
In certain cases, you might want to identify a particular page as the main source of information for a given topic, especially if the topic cites two or more pages. You can identify the main page by marking the page number in bold.
application gateway, 211, 345–351
·
·
·
dragging operations, 13, 37, 114
In a page range spanning several pages of a numbered chapter, separate first and last page numbers with a space, the word “to,” and another space. For example:
screen adjustments, 1-6 to 1-12
In a consecutively numbered page range, use an en dash to separate page numbers. For example:
screen adjustments, 6–12
The index is subject to many of the same typographic style conventions found in the text of the document itself. For example, if file names and commands appear in monospace font in your book, then they appear that way in the index.
core
file, 16
rlogin
command, 166
“See” and “See also” cross-references require special consideration. For more information, see “How to Use “See” and “See Also” References” on page 256.
Do not capitalize any word in an index entry unless the word is a proper noun, an acronym, or an abbreviation that is supposed to be capitalized. Use standard rules for capitalization.
subwindow button, 37
SunView accelerator, 34
If an entry is followed immediately by page references, insert a comma between the entry and the first page reference and between subsequent page references.
scrolling, 12, 16, 27
If you invert an adjective and a noun or noun phrase in an entry, separate them with a comma.
controls, window, 21
Use no punctuation between a primary entry without page numbers and subsequent secondary entries.
selection
adjusting, 6
extending, 59
A document needs an index if it has 20 or more pages. This rule applies to any type of document, from a user’s guide to a technical reference manual.
Indexing is an iterative process. Your first pass at an index is merely the foundation on which to build your final index. The first pass will be full of similar primary entries that you need to divide into secondary entries. When you first develop your index, you might introduce spelling errors and have incomplete page ranges in individual entries. Such errors can be corrected during the editing phase. See “Refining and Checking an Index” on page 263 for possible solutions.
Generally allow one full day for indexing for every 25 pages of text. A 100-page document might take four full days to index. An experienced indexer might require less time; a first-time indexer might require more time. Certain types of documents are much more difficult to index than others. Those documents require even more time than given in this guideline.
The first decision you need to make when starting to create an index is to determine which of the following parts of a document to index:
Front matter. Do not index the title page, copyright page, table of contents, and lists of figures, tables, and examples.
Preface. Index the preface if it contains information about the subjects within the document and not just why the document was written. Topics you might index in a preface include prerequisite knowledge, other applicable documents, or document conventions.
Chapters. Use the main body of the document as the source for most of the index entries.
Tables and figures. Index topics within tables and figures if they are of particular importance to the discussion. Do not index items within tables that merely reproduce information already contained in the text. Including index references to the subjects of the tables and figures themselves is often helpful to a reader.
Footnotes. Index footnotes if they expand on the information in the text. Do not index footnotes that merely document statements in the text.
Appendixes. Index appendixes if they contain pertinent material omitted from the main body of the document. Do not index appendixes if they merely reproduce information already contained in the main body. A quick reference in an appendix, for example, is usually not indexed. Nor is a questionnaire. Worksheets in an appendix are indexed unless they merely repeat the main text.
Back matter. Do not index terms in a glossary if they are explained elsewhere in the document. Do not index a bibliography or a reader comment form.
When you take on the task of creating an index, you must first decide what the pertinent statements or topics are. A topic can be a single word, a phrase, or even a concept. A topic has no minimum or maximum size.
As you analyze a topic, decide whether the topic contains information a reader might expect to find in the index. If it does, create one or more index entries.
To determine whether a topic requires an index entry, analyze the topic for the following attributes:
Describes how to perform a task. Tasks are the key subjects in certain types of documents, such as installation manuals.
Contains a definition of a term, acronym, or abbreviation. Definitions are frequently the key to a reader’s understanding of the document. An effective index makes it easy for a reader to find the definition or, similarly, an acronym or abbreviation. However, do not identify in an index definitions, acronyms, and abbreviations by glossary page numbers, but rather by text page numbers. See “Create Index Entries for Acronyms and Abbreviations” on page 252.
States a restriction, such as a Caution. Awareness of the restriction might help a reader avoid costly mistakes.
Explains a concept or an idea. This type of topic is most helpful to a reader. However, creating index entries that describe a concept or an idea is fairly difficult. The difficulty is in describing the whole concept in a few words.
Frequently, superfluous entries are in an index because the person creating the index refers to every occurrence of selected words or phrases in the document. The index is not a concordance, but rather an information retrieval device.
For example, assume that the following sentence appeared in the text being indexed:
Separate chapters of this manual discuss the use of disk and tape storage devices.
In this example, the sentence provides no information about disk or tape storage. Therefore, a reader would gain nothing from these index entries:
disk storage, 37
·
·
·
tape storage, 37
Include entries in an index only if they refer a reader directly to useful information.
Do not use entries so general that they apply to a global level of information. Such an entry is too broad to inform a reader of the entry’s corresponding content in the text.
For example, do not include entries such as “File Manager, creating files in” in a book about File Manager; or “features, of Netscape Navigator” in a book about this application. The only entries under the name of the application you are documenting address its use, for example, entries such as “installing” or “quitting” the application.
Terms for common procedures and commands might differ, depending on the technology or company. If you know of a common synonym for a process or command, include an entry to direct a reader to the term used in your book, as shown in these examples:
abort, See cancel
delete, See cut
search, See find
Using headings as the basis for index entries results in an index that is hard for the reader to scan.
Incorrect | Correct |
---|---|
running the QuickView utility, 42 | direct virtual memory access (DVMA), using, 87 |
using direct virtual memory access (DVMA), 87 | hidden file, definition, 28 |
What is a hidden file?, 28 | QuickView utility, running, 42 |
An editor can help you decide whether including “commands” as an index entry is useful. If you decide to include “commands” as a primary entry, follow it with subentries for each command appearing in the book.
commands
aset
chmod
Once you have determined that a topic merits an index entry, find one or more ways to describe it to a reader. The descriptions that you create become the subjects of the index entries. To describe a topic, follow these guidelines:
Anticipate a reader’s needs.
Select the proper words for the subjects.
Arrange the words for emphasis.
Create multiple entries (double-post).
Group the entries.
When a reader uses an index, it is usually to answer one of the following questions:
Where can I find information about a certain task, term, or topic?
Does the information described by an index entry tell me what something is, how it works, or how to use it?
Which pages can I ignore because they contain information I already know?
By anticipating a reader’s needs as you describe topics for your index, you can create an index that helps a reader find information quickly and easily.
When creating an entry, ask yourself whether you would be likely as a reader to look in the index for that entry.
Questionable entries include the following:
Entries starting with terms such as “how” or “why”
Entries starting with irrelevant terms
Commands or widgets used only in sample programs or examples
For example, in a book in which an exercise involves creating the buttons “Hello!” and “Adios!,” do not include “Hello!” and “Adios!” as index entries.
Titles of books in a “Recommended Reading” section
Entries that use the same phrasing as section headings
The words that you select are an abstract of the topic. Choose words that are as descriptive as possible. Using words from the text as subjects of index entries might satisfy readers who know the terminology used in the document. For other readers, provide subjects or cross-references worded so that they can find the desired information without specific prior knowledge.
Use a gerund, not an infinitive or a plain verb, as the main subject of an index entry when appropriate. For example, use “initializing” rather than “to initialize” or “initialize.”
Identify each entry for a computing term by including the type of entry after its name. For example, this type might be a command, file, function, or attribute:
apropos
command
width attribute
Typically, make the most important word the first word of the subject. The choice of most important word depends on what you want to stress or what is most important to a reader. For example, if the words you choose to describe a topic are “pixwin background color,” the primary entries might be as follows:
background color, pixwin
color, pixwin background
pixwin background color
In general, index the plural forms of nouns.
clients
·
·
·
servers
The exceptions to this rule are nouns that are only singular or nouns that are only used in the singular in the context being documented. Another exception is proper nouns such as the names of applications.
get
command
·
·
·
Tmark database
Keep in mind that certain terms require different fonts if you refer to the terms in different contexts. You also need to include a word such as “command,” “file,” or “directory” after such terms to further clarify the entry.
quit
command
quit, in contrast to exit
Grouping entries means combining entries that have common first words into primary entries and secondary entries.
Ungrouped Entries | Grouped Entries | |
---|---|---|
SBus, introduction SBus block diagram SBus specifications |
SBus
|
Primary entry Secondary entries |
When selecting a subject to be followed by secondary entries, be careful to group subjects properly. Do not merely select a word or phrase for a subject because it is common to several entries.
For example, assume that the following subjects appeared in your document:
igneous rock
metamorphic rock
rock music
To isolate “rock” and create three secondary entries is incorrect. If you analyze the use of “rock” in each entry, you can see that it is used in two different ways.
Incorrect | Correct |
---|---|
rock
|
rocks
rock music |
You want readers to be able to locate the various restrictions or ease-of-use features in your document, including the following:
Sets of rules
Value limits (maximums and minimums)
Incompatibilities between features and options
Caution notices
Ease-of-use Notes or Tips
Most of the topics that qualify as restrictions are not stated as such in the text. You must analyze the text to find the restrictions to index. Write index entries so that the subject describes the nature of the restriction.
You can also index those Notes or Tips that provide ease-of-use information or features.
Make sure to enable readers who are familiar with the document organization to ignore the entry if they already know the restriction or feature.
Incorrect | Correct |
---|---|
symbolic names, restriction | symbolic names, maximum length of |
Window menu shortcut | Window menu shortcut, F9 key |
In many documents, certain restrictions are identified specifically because of their importance. For example, assume that the following Caution notice appears in your document:
Caution — Never turn the system unit on or off while a diskette is in the disk drive. You might damage the diskette.
Index this restriction flagged with the word “Caution.” The entry might be as follows:
turning system on or off, Caution notice
Include an acronym or abbreviation in your index if it is unique to your document or documentation set and if it is not likely to be found in common usage. Many acronyms and abbreviations need not be included in an index. For example, the abbreviations for most units of measure, such as Btu, in., or lb, are not good candidates for indexing.
Alphabetize acronyms and abbreviations as words, rather than as the spelled-out version of the acronym or abbreviation. When you include an acronym or abbreviation in an index, follow it with the word or words from which it was formed. Place those words within parentheses.
CCP (console command processor), 1-5
Double-post the entry by adding an entry for the words that form the acronym or abbreviation, followed by the acronym or abbreviation in parentheses.
console command processor (CCP), 1-5
Double-posting means identifying a topic in two different places in an index. For example, a topic that appears as “address switch” and “switch, address” is double-posted in the index. A topic that appears in three places is triple-posted, and so on.
Entry | Double-Posted or Triple-Posted Entries |
---|---|
power indicator |
power indicator indicator, power |
Entry | Double-Posted or Triple-Posted Entries |
---|---|
C shell command interpreter |
C shell command interpreter command interpreter, C shell interpreter, C shell command |
Be careful of over-indexing with double-posting. Certain entries do not deserve double-posting. For instance, the following example might be acceptable in a document that refers to only a few commands.
Entry | Double-Posted Entries |
---|---|
|
command, |
However, for a manual with many commands, the entries under “command” might grow too numerous. In this case, rather than creating a primary entry of “command” with many secondary entries, index the commands under the command name and do not double-post the entries. Instead, include a cross-reference.
Entries | Double-Posted Entries |
---|---|
· · · |
commands, See specific command names |
Double-posting increases the number of index entries available to a reader, which broadens the scope of the index. The knowledgeable reader is not forced to scan the index for a general entry when seeking a specific topic.
Double-posting has a dramatic effect on usability. It is an essential technique for creating a high-quality index. Try to double-post entries for all key concepts and important terminology.
Keep in mind, however, that double-posting an index can affect your schedule. Because an extensively double-posted index provides a denser, more comprehensive view of a document’s topics, be sure to include enough time in your schedule for double-posting your index.
You cross-reference index entries by creating “See” and “See also” references.
Use a “See” reference when you have so many secondary entries that repeating them is unreasonable.
configuration, See measurement configuration
·
·
·
measurement configuration
applying storage thresholds
calculating line speeds
defining data fields
defining entities
Use a “See” reference to send readers from a broad category to a more specific category.
The next example is valid only if there are several secondary entries under “display thresholds,” “exception thresholds,” and “storage thresholds.” Otherwise, you would double-post.
thresholds, See display thresholds; exception thresholds; storage thresholds
Use a “See” reference to direct a reader from a term not used in the document to a term that is used as an index entry.
cars, See automobiles
Consider using a “See also” reference to direct a reader to related information at another index entry.
Depending on how your index is structured, you might also use a “See also” cross-reference from a specific category to a general one.
dBASE, 37
See also database applications
Use a “See also” reference to avoid fourth-level entries.
performance database
See also update, performance database
backing up data in
deleting
updating
·
·
·
update, performance database
automatic
displaying status
manual
starting
stopping
Clarify index entries for some noun modifiers, such as “data” and “file,” that are ubiquitous.
If you have several long and complicated entries that start with the same word, readers might not look far enough to find a given topic. In this case, use a “See also” reference to help a reader.
data
See also data files; data records
collecting
deleting
Never use a “See” reference with an entry that includes a page number.
Never include a page number in a “See also” reference.
Incorrect | Correct |
---|---|
structured files, 7-3
structured files, 7-3
|
structured files, See files, structured structured files, 7-3
|
Make sure that a “See” or “See also” reference repeats the exact wording of the entry to which it refers.
Incorrect | Correct |
---|---|
database, See PDB | database, See performance database (PDB) |
· · · |
· · · |
performance database (PDB) | performance database (PDB) |
Do not use unnecessary “See” references.
If you can reasonably double-post an entry, do so. Readers have every right to be upset if you send them elsewhere in an index just for one or two page numbers.
Incorrect | Correct |
---|---|
command objects, See objects | command objects, 5-2, 5-8 |
· · · | · · · |
objects, 5-2, 5-8 | objects, 5-2, 5-8 |
In particular, do not send readers from a specific entry to a general entry, under which they must then search for the specific entry. However, be careful that you include general information under the specific entry as well. In the following example, “changing report attributes” must be under the entries for specific reports because a reader might not look at the general entry.
Incorrect | Correct |
---|---|
forecast reports, See reporting
reporting
|
forecast reports, 3-67
reporting
|
Do not use a “See also” reference to send a reader to a duplicate (double-posted) entry in an index.
Incorrect:
entry-sequenced files, 7-3
See also files, entry-sequenced
·
·
·
files, entry-sequenced, 7-3
Here are basic formatting and punctuation rules for “See” and “See also” references:
Italicize the words “See” and “See also.”
base window, 45
See also pane
Never include page numbers with “See” and “See also” references.
Use those references to direct a reader to another index entry.
floppy, See diskette
Place the “See” reference on the same line as the index entry, separated with a comma.
search, See find
Place the “See also” reference at the beginning of the entry.
Place the “See also” reference on a line by itself, and indent the reference from the line above.
aggregation scheme, 16
See also summarization, data
Use a semicolon to separate multiple “See” and “See also” references.
local area network, 24
See also Ethernet; standards, networking; wide area network
For secondary entries, use “See” and “See also” references as follows.
Incorrect | Correct |
---|---|
files
files, editing, See files, printing, 35
|
files
|
This section explains some established rules for indexing. If you disregard them, you might confuse or annoy readers. You might also appear incompetent to any reader who is knowledgeable about indexing.
If you can use the primary entry alone, do so. A primary term with only one secondary term must be on a single text line. If you feel that the primary entry alone is misleading, rewrite it.
Incorrect | Correct |
---|---|
optimization routines
|
optimization routines, 38
optimization routines, use of, 38 |
Use adjectives with related nouns to provide enough information for a reader.
Incorrect | Correct |
---|---|
implicit
|
implicit commands
|
This rule applies to noun modifiers, that is, nouns that are being used as adjectives. This rule eliminates awkward, confusing constructions in which the primary entry is a noun relative to some secondary entries and an adjective relative to others.
Incorrect | Correct |
---|---|
data
|
data
data files, 90 data records, 47 · · ·
|
Generally, if a primary entry is followed by half a page or so of secondary entries, either the primary entry is too broad or you are over-indexing. For example, in a printer manual, the primary entry “printer” is too broad to be indexed as a term.
If you feel that it is necessary or helpful, use “commands” plus a “See” reference to send a reader to alternate methods of locating a given command.
Incorrect | Correct |
---|---|
commands
|
(no entry at all, if most of the document describes commands) or commands, See individual commands by name or commands, summary of, 18 |
For manuals that have a repetitive structure, do not provide so many entries that they get in a reader’s way. For example, in a reference manual containing many commands or utilities, you might be tempted to index the subheadings under each command. This often results in over-indexing, as shown in the following tables.
Incorrect | Correct |
---|---|
|
|
Over-indexing also occurs if you create several secondary entries under a primary entry when all entries are on the same page.
Incorrect | Correct |
---|---|
input devices
|
input devices, 167 |
Do not provide two adjacent entries that are very similar. However, always double-post acronyms and abbreviations even if it is possible that the entries might be adjacent in the index. The test: If you omit an entry, can a reader still find the right place in the document?
Incorrect | Correct |
---|---|
deleting a file, 41 |
|
Some kinds of under-indexing are very obvious because they do not provide enough specific information to be useful.
Incorrect | Correct |
---|---|
reports, 31–39, 77 |
reports
|
Other types of under-indexing are not obvious, except to a reader. It is especially important to index concepts, not just the terms that appear in the document.
Incorrect | Correct |
---|---|
|
· · · backing up data to tape, 77 · · · tape backups, 77 |
Alphabetize subentries by keyword, not by beginning articles, conjunctions, or prepositions. Reword subentries so that the keyword or key term, rather than an irrelevant introductory word, appears at the beginning of the subentry. If the subentry requires an article, conjunction, or preposition to flow correctly, try to include these additional words at the end of the subentry rather than at the beginning.
Incorrect | Correct |
---|---|
accounting
addressing
backing store
|
accounting
addressing
backing store
|
For path, file, or variable entries that begin with a symbol, alphabetize these entries by the first letter of the first word following the symbol.
Incorrect | Correct |
---|---|
Symbols
E error reporting external files |
C
Create menu E error reporting
external files I ID numbers
P
primary numbers |
While creating the first draft of an index, you probably concentrated on the individual entries and their secondary entries. While editing the index, you are concerned with the index as a whole.
Editing an index might require that you create or delete entries, combine or split entries, and regroup or reword entries. In a sense, editing an index is not very different from editing the document. Namely, you verify that all necessary material is included, that it is in the intended order, and that it is error free.
Remember that you are reading an index in an abnormal way, that is, you are reading it from start to finish. Normally, readers search directly for the word or phrase they hope to find. Because you are reading an index this way, you might think that many entries are not necessary or are redundant. For some entries, this might be true, but to delete many entries on that basis alone is risky. Unless your analysis of the topic was incorrect when you created the entry, you probably had a specific reason for adding the entry.
The following sections review common problem areas in indexing.
Many publishing systems do not check the spelling in the embedded index entries when the spelling checker is run on the body of the document. For this reason, always carefully proofread and run the spelling checker on index entries to catch spelling and typographical errors.
Check the subjects to determine whether slight variations in wording are intentional or whether you should use only one wording. If there are valid subjects that differ only slightly in wording, examine them to be sure that readers can recognize the difference. You might have to reword the subjects to make the differences apparent.
After creating the index, you might discover that you have used inconsistent terminology in the document. A consistency check and any necessary corrections are well worth the time it takes to standardize terminology.
For example, “AdminTool” might also appear as “Admin Tool”; “Administration Tool”; and “setting up, configuring.” You also must standardize usage for terms such as “home directory” and “root directory,” and “superuser” and “root user.”
Check the entries for the misuse of singular forms and plural forms. Usually, only one form of a subject is justified. If you find more than one, combine secondary entries under one subject. Using both forms of a subject, such as “data set” and “data sets,” can cause errors. Several other entries and their subsequent secondary entries might intervene between the singular and plural forms of a subject. Spare readers the trouble of checking the index for both forms.
Incorrect | Correct |
---|---|
data set
data set address data set area data sets
|
data sets
|
Check that all meaningful variations of a subject’s wording appear in an index. See “Group Entries” on page 250.
Include no more than two to four page references per index entry. If an entry has more than two to four page references, see if you can create secondary and tertiary entries to reduce the number of page references.
Incorrect | Correct |
---|---|
block diagram, 21, 28, 33, 37, 45 |
block diagram
|
Check that the page references for each occurrence of a topic are the same and that they appear in each place. In the example, a reader looking up “operator messages” would not be aware of all the other places where information exists. Create secondary entries under “operator messages” and give readers the same information they would have found had they looked up “messages.”
Incorrect | Correct |
---|---|
messages
operator messages, 2-34, 3-7 · · · |
messages
operator messages
|
Check that each “See” reference refers to an entry with secondary entries. Read “Creating “See” and “See Also” References” on page 253.
One form of a bad page break results when a primary entry with multiple secondary entries and perhaps tertiary entries breaks in the middle at the foot of the last column on a right page. The first column on the following page begins with an indented secondary or tertiary entry. Bad page breaks cause problems for a reader, who must look back to the previous page to find the primary entry.
Correct bad page breaks by repeating the primary entry above the carried-over secondary entry followed by the word “continued” in italic and surrounded by parentheses.
graphical user interface
|
graphical user interface
|
Avoid having a single primary entry at the beginning of an alphabetic section at the bottom of a column. Force the alphabetic character to the top of the next column, carrying the single primary entry along with it.
Likewise, do not leave a single line at the end of an alphabetic section at the top of a column. Force a column break one or two lines before the widowed line.
When refining your index, examine secondary entries carefully in the following problem areas.
Check the levels of secondary entries so that proper indentation shows the relationship of one entry to the preceding one. See “Nested Entries” on page 242.
Check main entries that are followed by secondary entries having the same page reference.
In many cases, you can eliminate the secondary entries because a reader can find all the information on one page. Redundant secondary entries often occur when items in a table are indexed. See “Do Not Over-Index” on page 259.
Incorrect | Correct |
---|---|
data sets
|
data sets, 2-7 |
Check whether a secondary entry can also appear as a primary entry. If it can, verify that it exists as such or create the primary entry and insert it in the proper place.
Check whether secondary entries can be rearranged to stress a certain point. In this example, all three secondary entries can be in the same form. The form depends on what you want to stress.
Incorrect | Correct |
---|---|
window system
|
window system
|
Review an index to make sure that you have combined relevant entries.
Incorrect | Correct |
---|---|
DeskSet
DeskSet atoms, 4-8 DeskSet drag-and-drop atoms, 4-4 DeskSet drag and drop handshaking, 4-2 DeskSet integration
|
DeskSet
|
Check for secondary entries that can be arranged under one topic rather than several. Such division of secondary entries is usually the result of misused “See also” references.
Incorrect | Correct |
---|---|
find function
search function
|
find function
search function, See find function |
Check for and move a secondary entry if you included the combined term as a separate entry.
In the next example, the entries starting with “database” under the “classing engine” main entry belong under the “classing engine database” main entry.
Incorrect | Correct |
---|---|
classing engine
classing engine database
|
classing engine
classing engine database
|
Check that the number of secondary entries under various forms of the same topic are all the same. In the example, “attention key” appears after the “terminal, communications” entry so that readers are aware of the information regardless of how they look it up.
Incorrect | Correct |
---|---|
communications terminal
terminal, communications
|
communications terminal
terminal, communications
|
After you have edited the index, compare the size of the index with the size of the document. Although the index size is not an indication of its quality, an index that is too small for the size of the document is suspicious and might indicate serious omissions.
A minimum length for an index is one page of index entries for every 20 pages of text, or about one index entry for every 100 words of text. This can be considered a “5 percent” index. For dense technical material, however, this guideline is too low. For a dense technical manual, try to provide one page of index entries for every 10 pages of text, which can be considered a “10 percent” index.
If you check the length of your index by page count rather than by word count, do not count text pages that contain any of the following if they occupy more than about two-thirds of a page:
Flow diagrams
Figures
Code examples
Front matter (title page, table of contents, and so on)
Blank space longer than three-quarters of a page
Glossary or bibliography
If the index falls below the guidelines, check that all topics in the document are entered in the index.
The type of index most writers work with is the “back of the book” variety. A global index combines the back-of-the-book indexes from all the books in a set. A global index is a valuable information retrieval device for a reader who is not familiar with all the books in a set. A global index provides a single place where readers can find the information they seek without having to look through several individual indexes.
In a global index, merely referring a reader to page numbers is insufficient. Because a global index combines the indexes from several books in a set, a reader also needs to know the book in the set to which the reference applies. For this reason, a global index requires a special page numbering style. One method is to use a four-letter abbreviation for an entry’s book title, with a running footer that provides a legend on each index page for the abbreviations. If such a footer is not possible or desirable, put a legend for abbreviations at the beginning of the index.
Because of its size and complexity, a global index is by far the most difficult type of index to create properly. You cannot just combine the indexes from several books and assume that, if the previous back-of-the-book indexes were correct, a global index will also be correct.
When combining indexes to make a global index, the indexer must edit the global index for most of the indexing mistakes described under “Refining and Checking an Index” on page 263. Specifically, the indexer must check for the following:
Consistent page numbering style
Levels of secondary entries
Differences in wording
Misuse of singular and plural forms
Meaningful variations (double-posting) of a subject’s wording
Possible rearrangement of secondary entries
Bad page and column breaks
Many of these mistakes might be in a global index even though they might not be in the original indexes. These mistakes happen when common terms in different indexes are combined, slightly different terminology is used in different books, and different indexing choices have been applied in each book.
There are two ways to fix the problems that result from creating a global index:
Edit the index entries in the original text and re-create the index.
Edit the global index and leave the index entries as they are in the original text.
If your writing tool supports an online index, consider including one to help readers scan the content of your document and quickly find what they need.
Multiple page numbers translate into many links next to an entry in an online index. So while in print you can collapse repetitive entries, for online indexes elaborate them as much as possible to help the readers find the correct entry quickly.
Incorrect | Correct |
---|---|
|
|
An online index simplifies and expedites a reader’s search for specific information much more than a search engine. A search engine alone can be inadequate for finding information quickly, especially if the tool searches a large database of documents.
For instance, a search engine scans text looking for occurrences of the word or phrase typed in the search box. Then, it lists every document that contains any mention of the word or phrase. A reader can lose a considerable amount of time sifting through these documents before finding the desired information. Also, a search engine cannot provide a topic analysis or overview of the document.
In addition to following the guidelines for a good print index, a good online index makes full use of hypertext by linking index entries to the relevant text in your document.
18.220.127.68