DITA Brief with Tiny Examples

DITA is an XML standard for topic-based authoring—modular, reusable content assembled with maps and extensible via specialization.

The Core: topic

A topic is a self-contained unit of information.

<topic id="t-hello">
  <title>Hello DITA</title>
  <shortdesc>DITA organizes content into modular topics.</shortdesc>
  <body>
    <p>This is a paragraph.</p>
  </body>
</topic>

Cross-reference between topics:

<p>See <xref href="install.dita#task-install"/> for steps.</p>

Standard Topic Types

concept explains what something is

<concept id="c-what">
  <title>What is Widgets Mode?</title>
  <shortdesc>Gives high-level understanding.</shortdesc>
  <conbody>
    <p>Widgets Mode groups tools for quick access.</p>
  </conbody>
</concept>

task explains how to do something

<task id="task-install">
  <title>Install the Widget</title>
  <shortdesc>Step-by-step procedure.</shortdesc>
  <taskbody>
    <steps>
      <step><cmd>Open the installer</cmd></step>
      <step><cmd>Accept the license</cmd></step>
      <step><cmd>Click <uicontrol>Install</uicontrol></cmd></step>
    </steps>
  </taskbody>
</task>

reference provides factual or lookup data

<reference id="r-ports">
  <title>Network Ports</title>
  <refbody>
    <table>
      <tgroup cols="2">
        <thead>
          <row><entry>Port</entry><entry>Purpose</entry></row>
        </thead>
        <tbody>
          <row><entry>8080</entry><entry>HTTP Alt</entry></row>
          <row><entry>8443</entry><entry>HTTPS Alt</entry></row>
        </tbody>
      </tgroup>
    </table>
  </refbody>
</reference>

Assembling Topics with Maps

A DITA map collects topics and defines structure, keys, and filtering.

<map title="Widget Guide">
  <topicref href="c-what.dita"/>
  <topicref href="task-install.dita"/>
  <topicref href="r-ports.dita"/>
</map>

Filtering/audience control:

<topicref href="task-install.dita" audience="admin"/>

Extending DITA (Specialization)

You can specialize to create domain-specific topic or phrase types that inherit processing and semantics from their bases.

Example A — New topic type (policy)

<policy id="p-passwords">
  <title>Password Policy</title>
  <shortdesc>Defines password requirements.</shortdesc>
  <body>
    <section>
      <title>Rules</title>
      <p>Minimum 12 characters; rotate every 90 days.</p>
    </section>
  </body>
</policy>

Example B — New inline type (button)

<p>Click <button>Run</button> to start the process.</p>

Reuse Across Topics

Conref pulls shared chunks by address; keyref uses map-defined keys for indirect addressing.

Conref:

<p>Contact support at <ph conref="snippets.dita#snps/support-email"/>.</p>

Keyref (map + topic):

<!-- in map -->
<keydef keys="support-email" href="snippets.dita#snps/support-email"/>

<!-- in topic -->
<p>Email us: <xref keyref="support-email"/>.</p>