Maintaining accurate and valid cross-references in DITA content is vital to ensure the usability and reliability of technical documentation. DITA offers specific mechanisms to help guarantee that cross-references remain up-to-date and functional over time.

Keyref and Conkeyref Attributes

DITA uses attributes like <keyref> and <conkeyref> to establish and maintain cross-references. These attributes link content within topics, ensuring that references automatically adapt to changes. When a referenced topic is updated, the keyref attributes ensure that cross-references within other topics stay accurate.

Validation and Testing

Regular validation and testing procedures are essential to confirm the validity of cross-references. Automated tools and scripts can be employed to check for broken or invalid references. For example, if a referenced topic is deleted or renamed, automated checks can detect these issues and alert content creators, allowing them to rectify the cross-references promptly.

Example:

Here’s an example of how keyref attributes are used to maintain cross-references:

<topic id="user-manual">
  <title>User Manual</title>
  <content>
    <p>This manual provides instructions on using the product.</p>
    <p>For more information, refer to the <link keyref="troubleshooting-topic"/></p>
  </content>

In this example, the keyref attribute is used in a link element to reference a topic titled “Troubleshooting.” If the title of the referenced topic changes or the topic is updated, the keyref attribute ensures that the cross-reference remains accurate.