What are reference topics in DITA XML?

November 10, 2023
|By Bryan Tipper

Reference topics in DITA XML are a valuable element for providing information that users can refer to when they need details about specific terms, concepts, or components. These topics serve as a centralized source of information that can be linked to from various locations within your documentation. Reference topics help ensure consistency and accuracy when explaining common terms or objects.

Structure of Reference Topics

Reference topics follow a particular structure, making them easy to access and understand:

  • <title>: This element provides a clear and concise title for the reference topic, often representing the term or concept being described.
  • <prolog>: Within the <prolog> element, you can include metadata and other information about the reference topic, such as definitions, synonyms, and usage guidelines.
  • <body>: The <body> element contains the main content of the reference topic, including detailed explanations, examples, and any relevant information related to the term or concept.

Example:

Here’s an example of how a reference topic is structured in DITA XML:


<topic id="reference_example">
  <title>API Documentation</title>
  <prolog>
    <metadata>
      <subject>Documentation</subject>
      <definition>An API documentation is a set of documents that describe the functions and features of an application programming interface (API).</definition>
    </metadata>
  </prolog>
  <body>
    <p>API documentation is essential for developers who want to understand how to use an API to integrate with a software application. It provides details on endpoints, request and response formats, authentication, and usage examples.</p>
    <p>Good API documentation enhances developer experience and fosters successful integration.</p>
  </body>

In this example, the reference topic “API Documentation” is structured with a title, a prolog that includes metadata and a definition, and the body containing detailed information about what API documentation is and why it is important.