How does a DITA map differ from a DITA topic?

November 10, 2023
|By Bryan Tipper

A DITA map and a DITA topic serve distinct purposes in DITA documentation. A DITA map is a structural element that organizes and links topics, acting as a table of contents and navigation guide, while a DITA topic contains specific content with a defined structure, providing information on a particular subject.

A DITA map is a high-level container document that plays an organizational role. It outlines the structure of a document or a collection of topics, arranging them in a specific order, and providing navigation. It’s like a table of contents that helps users find their way around a set of topics.

A DITA topic, on the other hand, is a self-contained document that contains specific information about a single subject. Topics are where actual content resides and are the building blocks of DITA documentation. They adhere to a predefined structure, typically including elements such as <title>, <body>, and <section> to present content in a standardized format.

Example: DITA Map

An organization creates a DITA map for its product’s user guide. 

<!-- DITA Map -->
<map>
  <title>Product User Guide</title>
  <topicref href="introduction.dita"/>
  <topicref href="getting_started.dita"/>
</map>

In this DITA map example, the focus is on the organizational structure of a “Product User Guide.” It references specific DITA topics, such as “introduction.dita” and “getting_started.dita,” arranging them in the desired order.

Example: DITA Topic

Meanwhile, the referenced topic contains the actual content of the final document. 

<!-- DITA Topic -->
<topic>
  <title>Introduction to the Product</title>
  <body>
    <p>This is the introduction to our product...</p>
  </body>
</topic>

In contrast, this DITA topic contains specific content related to the introduction of a product. It includes elements like <title> and <body> to structure and present the topic’s content. Topics are meant for detailed content on a single subject, while maps help organize and navigate these topics within a document or documentation set.