This article presents a high-level overview of how to begin creating an index using individual .DITA topics in oXygen. Previously, it was recommended that if creating an index, one could use an <indexterm/> element placed within the <conbody/>, <taskbody/>, or <refbody/> elements.
With a renewed effort to incorporate metadata within a <prolog/> element, the decision was made to incorporate <keyword><indexterms><indexterm></> elements. As we make the transition from a file system-based repository to Vasont, each topic template will contain a prolog structure containing the above <keyword><indexterms><indexterm></> elements.
Technical Implementation
The indexterm element is pure metadata, and does not display. You should place index entries in the prolog section of the topic, or in the topicmeta section of the topicref in the ditamap only if the term is specific to a particular publication.
The alphabetical index of a publication is derived, during the publishing process, from index keyword terms placed by the author throughout topics in the document. Index keyword terms are defined through the indexterm element.
- the topicref in the ditamap
- the prolog in the topic
- the shortdesc (and abstract) in the topic
- the body of the topic
However, having index entries scattered throughout the text creates maintenance problems, and may lead to difficulties in translation and processing.
Where possible, indexterm elements should be placed in the topic prolog section, outside the body of the topic content. In the prolog, index entries must be contained within akeywords element.
Recommended: when specific to a publication (and therefore not always applicable to the topic), the indexterm elements should be placed in the topicmeta section within the topicref element in the ditamap. An example of this may be a term that is used by one organisation but not others, where different ditamaps define output for different organisations.
In some cases, you may feel you want to use an indexterm at a particular point in the document where indexterm is not allowed. Although you may be able to technically work around the problem by inserting a phrase (ph) element and then inserting the indexterm element is the ph element, do not do this. Only insert an index term where the element is valid.
Indexing Guidelines
1. Start with your topic headings.
Add one or more index entries for each topic heading. Don’t forget to consider capitalization. As a general rule, use lower-case, except for proper nouns. This is a good first pass through your document.
2. Consider other words that users might look for to find these topics.
Go through the topic headings a second time and consider other words that a user might use to find the topic. For example, if the topic is about restarting the computer, you might add another entry under “reboot” for users that know that term.
3. Look for keywords in each topic.
Look through each topic to find keywords that a user might search for. These might include the names of dialog boxes or windows, or unfamiliar terms, for topics that include a definition of the term.
4. Think of synonyms for the keywords.
Find synonyms for the keywords you identified in the previous round. Consider your audience and terms they might be more familiar with.
5. Brainstorm other words users might look for.
Think of the product you have documented and brainstorm any other words a user might search for.
6. Read the completed index.
As with all your writing, be sure to read through the completed index, carefully checking for spelling errors and typos.