When should you rely on an index, and when is a search feature more appropriate?

November 10, 2023
|By Bryan Tipper

Deciding whether to rely on an index or use a search feature in your DITA documentation depends on the specific needs of your users and the nature of your content. Each approach has its advantages and is suitable for different scenarios.

Index Usage

An index is valuable when you want to provide users with a curated and organized list of important terms, concepts, or keywords found in your documentation. It’s particularly useful when your content has well-defined and frequently referenced terms that users need to locate quickly. Index entries are typically created and maintained manually, allowing authors to highlight specific topics or key points. This approach is beneficial when you want to guide users to essential information systematically. For instance, in a technical manual, an index might help users find information on specific features, functions, or troubleshooting steps.

Search Feature Appropriateness

A search feature, on the other hand, is more appropriate when your documentation contains a vast amount of information, and users may need to search for a wide range of topics or keywords. It provides users with the flexibility to explore the entire content based on their unique search queries. Search functionality is highly effective when users are looking for information that may not be explicitly indexed or when they need to find less frequently referenced details. It’s also suitable when your content is frequently updated or expanded, as it automatically includes new information in search results. For example, in a comprehensive knowledge base, a search feature enables users to find answers to a wide variety of questions quickly.

Example:

Here’s an example illustrating the difference between index usage and a search feature in DITA documentation:


<index>
  <indexterm>
    <primary>Topic A</primary>
  </indexterm>
  <indexterm>
    <primary>Topic B</primary>
  </indexterm>
</index>

<topic id="topic_a">
  <title>Topic A</title>
  <body>
    <p>This is the content of Topic A.</p>
  </body>
</topic>

<topic id="topic_b">
  <title>Topic B</title>
  <body>
    <p>This is the content of Topic B.</p>
  </body>
</topic>

<search>
  <query>Topic A</query>
  <results>
    <topicref href="topic_a"/>
  </results>
</search>

In this example, we have both index entries for “Topic A” and “Topic B” and a search query for “Topic A.” The index entry guides users directly to “Topic A,” while the search feature also locates “Topic A” based on the query, providing users with multiple ways to access the information.