How are link types documented and communicated in DITA projects?

November 10, 2023
|By Bryan Tipper

In DITA projects, documenting and communicating link types is a crucial aspect of ensuring consistency and clarity in your documentation. DITA provides a structured and organized way to define and manage link types, making it easier for authors and content contributors to understand and use them effectively.

1. DITA Topics: One common approach is to document link types within DITA topics. These topics can serve as a reference guide for authors and contributors, explaining the purpose and usage of various link types. You can create topics that provide detailed descriptions and examples of how to use each link type, making it easier for team members to follow best practices.

Example:

Here’s an example of how you can document link types using DITA topics:


<topic id="link-types-reference">
  <title>Link Types Reference</title>
  <body>
    <section>
      <title>Hyperlink (<code><link></code>)</title>
      <p>The <code><link></code> element is used to create hyperlinks to external resources or other topics within the DITA project. Here's an example of how to create a hyperlink:</p>
      <pre>
        <code><link href="https://www.example.com" text="Visit Example Website" /></code>
      </pre>
    </section>
    <section>
      <title>Cross-Reference (<code><xref></code>)</title>
      <p>The <code><xref></code> element is used to create cross-references to other topics within the DITA project. Here's an example of how to create a cross-reference:</p>
      <pre>
        <code><xref href="other-topic.dita" /></code>
      </pre>
    </section>
  </body>
</topic>

By documenting link types in DITA topics, you create a clear and accessible resource that helps your team understand and utilize links effectively in your DITA projects.