By, Aparna Mudaliar
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.
Which Parts of a Document Do I Index?
Which Topics Do I Index?
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
- 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
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
- spelled-out forms
Correct Incorrect Extraction, Transformation, and Loading (ETL) 3
ETL (Extraction, Transformation, and Loading) 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
Correct Incorrect data profiles
see data profiles
How Do I Index Special Characters?
- Use double-posted entries to index special characters. example, you can index currency symbols using double-posted entries
Correct Incorrect ¥ (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
removing non-essential constraints 22
- Individually list all the second level entries
Correct Incorrect centrality measures
degree-in and degree-out 101
- Specify conjunctions, prepositions, or articles at the end of the sub entries
Correct Incorrect degree centrality
overview of 62
parameters for 65
role expressions and 66
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
workflow steps 22
workflow steps 26
- Do not under-index. For example, do not exclude important features that can be marked as secondary entries
Correct Incorrect regulatory reports
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
About the Author
Aparna Mudaliar works as a senior technical writer with SAS R&D, Pune, India. She is currently working on user documentation and embedded user assistance for Flex-based web applications. She has keen interest in practicing meditation, participating in marathons, and cooking something exotic. You can reach her at firstname.lastname@example.org.
Aparna, thank you for such an informative article.
Thank you, Farheen! I’m glad that you find it useful!
It was a good refresher…the basics were touched upon
Thank you, Kavita!
Nice and informative article. Provides really good guidelines for indexing. Thanks for the article, Aparna.
Comments are closed.