As a technical writer, are you often in a
state of confusion and uncertainty when indexing your content? If your answer
is yes, then this article is for you! Here are a few guidelines that will help
you generate smart index entries. Moreover, these guidelines will also help you
maintain consistency across the index.
You might ask yourself the following
questions before starting the process.
|
Do’s
|
Don’ts
|
|
· Index the main body of the chapters.
·
Index the preface if it contains
important information such as prerequisites, hardware requirements, and so
on.
·
Index the appendixes if they
provide additional information about the topics that are documented in the
chapters.
|
·
Do not index the common
elements of the front matter:
·
title page
·
copyright
·
table of contents
· Do not index the common elements of the back matter:
·
glossary
·
bibliography
|
Which Topics Do I Index?
|
Do’s
|
Don’ts
|
|
· Index the task-oriented topics that explain users how to
accomplish a task.
·
Index the conceptual topics
that provide prerequisite or additional information to accomplish a task.
·
Index the cautions, notes,
tips, or restrictions that provide important information to the user.
·
Index the topics that explain
terminology.
|
·
Do not index the obvious
tasks. These obvious tasks have their own independent task-oriented topics.
For example, tasks such as creating, deleting, copying, and so on.
·
Do not index the topic that
merely mentions the term.
|
How Do I Select the Keywords?
·
For conceptual topics, specify
the keyword in the noun form.
·
Use the plural form if the
keyword does not represent a unique entity.
·
Include a modifier before the
noun wherever possible.
|
Correct
|
Incorrect
|
|
user roles 11
user groups 12
|
roles
11
groups
12
|
·
For task-oriented topics,
specify the keyword as an action with the gerund (ing) form of the verb.
·
Do not use heading titles that
represent the tasks as index entries.
|
Correct
|
Incorrect
|
|
configuring data profiles 22
|
configure data profiles 22
|
|
sequencing role definitions 20
|
sequencing a role definition 20
|
How Do I Index Acronyms
and Abbreviations?
Use double-posted entries for indexing
these items:
·
abbreviated forms
·
acronyms
·
spelled-out forms
|
Correct
|
Incorrect
|
|
Extraction, Transformation, and Loading
(ETL) 3
ETL (Extraction, Transformation, and
Loading) 3
|
ETL 3
Extraction, Transformation, and
Loading 3
|
How Do I Index Inversions and Synonyms?
·
Use double-posted entries to
indicate inversion of terms.
|
Correct
|
Incorrect
|
|
data loading 85
loading data 85
|
data loading 85
|
·
Use cross-references to
indicate synonyms. For example, you can add an index entry to indicate that
data profiles and table profiles are synonyms. Note that the cross referencing
index entry does not include the page number.
|
Incorrect
|
Correct
|
|
data profiles
assigning 22
configuring 24
table profiles
assigning 22
configuring 24
|
data profiles
assigning 22
configuring 24
table profiles
See data profiles
|
How Do I Index Special
Characters?
·
Use double-posted entries to
index special characters.For example, you can index currency symbols using
double-posted entries.
|
Incorrect
|
Correct
|
|
¥
105
|
¥ (Yen
sign) 105
Yen sign
(¥) 105
|
What Formatting Styles Do I Apply?
·
Use lowercase preferably.
·
Do not use lowercase if the
term itself is in uppercase or sentence case.
|
Correct
|
Incorrect
|
|
Basic
Properties pane 20
bulk
loading 30
CHART procedure 45
|
basic properties pane 20
Bulk
loading 30
chart
procedure 45
|
·
Restrict to two-level nesting
of index entries, primary entry and secondary entry.
|
Correct
|
Incorrect
|
|
constraints
defining 10
removing 22
|
constraints
defining 10
removing
non-essential constraints 22
|
·
Individually list all the
second level entries.
|
Correct
|
Incorrect
|
|
centrality measures
degree-in 101
degree-out
101
|
centrality measures
degree-in and degree-out 101
|
·
Specify conjunctions,
prepositions, or articles at the end of the subentries.
|
Correct
|
Incorrect
|
|
degree centrality
overview of 62
parameters for 65
role expressions and 66
|
degree centrality
overview 62
parameters 65
and role expressions 66
|
How Do I Index Just Enough?
·
Do not over-index. For example,
do not repeat secondary entries for each primary entry.
|
Correct
|
Incorrect
|
|
correction loads 21,
22, 25
incremental loads 25,
26, 28
|
correction loads
prerequisites
21
workflow
steps 22
parameters 25
incremental loads
prerequisites
25
workflow
steps 26
parameters 28
|
·
Do not under-index. For
example, do not exclude important features that can be marked as secondary
entries.
|
Correct
|
Incorrect
|
|
regulatory reports
generating 20
reviewing 21
authorizing 22
submitting 25
|
regulatory reports 20-25
|
·
Do not index adjacent entries
that are very similar. Retain one of them.
|
Correct
|
Incorrect
|
|
deploying jobs 21
|
deploy option 21
deploying
jobs 21
|
How Do I Review My Index
Entries?
·
Maintain a checklist to ensure
that you follow all the guidelines.
·
Focus on the primary and
secondary entries first. Subsequently, remove redundant entries and evaluate
the index as a whole.
·
Make sure that you use
consistent terminology across all your entries.
·
Request one of your peers who
is unfamiliar with your content to review your index entries.
Publication Details
This article was published in the Indus magazine. Please see:
Indexing organizes data for quick webspacekit
ReplyDeleteaccess, speeding up search and retrieval processes in databases or documents.