Indexing and keywords guidelines and tips

Last Updated : Mar 27, 2017 |

A good index can really help users find the content they’re looking for. Follow these guidelines to increase the quality of your indexes.

If there are terms that are relevant to the content that you don’t want to include in the index, you can add keywords in the prolog. This is useful for identifying things like terms not used in the product that a user might search for (for example, a user might search for an industry-standard term instead of the feature name Avaya has assigned to something). Keywords are searchable in our HTML outputs. Providing industry-standard terms and other additional relevant terms as keywords in the prolog will improve the findability of our HTML content and help the user locate the right topic. The keyword element is available under keywords in the prolog at the same level as indexterm.

General guidelines

  • Every topic that has content must contain an index entry. Topics with just titles and without content in it that are created for linking purpose don't necessarily require index entries.

  • Do not just index the topic title. Ensure that you index the subjects covered in the topic.

  • Include only text in index entries; do not tag the entries.

  • The most important consideration for indexing is to ensure that you consider how a user might look for information. There might be terms or words not included in the topic text that should be included as index terms. For example, there might be an Avaya feature name that is also commonly known by an industry standard term.

  • Insert index entries that refer to the entire topic in the prolog element (<prolog><metadata><keywords><indexterm>). Index entries entered in the prolog link to the page in which the topic title displays. It is always best to include index terms in the prolog of a topic whenever possible.

  • If you have a very long topic and want to add additional index entries, insert the index entry immediately following the start tag of the block element. But this should be very rare.

    Note:

    Do not insert index terms between the <title> element and the first paragraph in a <section> as it causes a little extra space to appear in the output. Instead, put the index terms in the first paragraph of the section.

  • Consider reversing the primary and secondary entries. For example, create users as a primary entry and adding as a secondary entry. Then, create adding as a primary entry and users as a secondary entry.

  • Do not create more than two levels of index terms.

  • When you have pointed to a particular word or phrase in the text, avoid moving an index tag within text that has not changed since the last time it was translated. A moved index term generates a fuzzy match because the segmentation of the sentence has changed from that stored in the translation memory.

  • You do not have to include punctuation to separate index entries, as they are automatically inserted where appropriate.

  • Be careful not to include extra spaces at the beginning or end of indexterm elements. Extra spaces in indexterm can cause your build to fail.

  • Do not leave empty index terms in any topics.

  • Use keywords as appropriate to enhance the findability of the content. Because keywords are only searchable in the HTML output, make sure that you include the important terms as index entries. Use the keyword element to include other terms that a user might search for that you don’t include in the index.

Secondary index entries

A secondary index entry is one that appears like this in an index:

Primary term
    Secondary term

The DITA markup used to express this relationship is this:

<indexterm>Primary term<indexterm>Secondary term</indexterm></indexterm>
Note:

The markup for the 'Secondary term' is entirely contained within the markup for the 'Primary term.' In other words, the indexterm containing the 'Secondary term' is a child element of the indexterm containing the 'Primary term.'

Tips

  • If you see a red underline in an index entry, indicating a spelling error, do not add any blank spaces to the beginning or end of the indexterm. If the spelling in the entry is correct, ignore the red line. Adding spaces to the beginning or end of the indexterm can cause output build issues.