Organization

Hierarchical Organization

DITA maps use nested <topicref> elements to create hierarchical relationships, similar to chapters and sub-chapters in a book.

Example:

<map>
  <title>Product User Guide</title>
  <topicref href="introduction.dita">
    <topicref href="getting-started.dita"/>
    <topicref href="basic-concepts.dita"/>
  </topicref>
  <topicref href="advanced-features.dita">
    <topicref href="customization.dita"/>
    <topicref href="integration.dita"/>
  </topicref>
</map>
      

This structure automatically generates navigation hierarchies in published output, eliminating the need for manual formatting or cross-reference maintenance. You can easily switch to a "Quick Start Guide" by using a different map that references only selected topics.

Conditional Organization

DITA maps can conditionally include or exclude content based on filtering attributes like audience, product, or platform. This allows different audiences to receive tailored content from the same topic set.

Example:

<topicref href="advanced-security.dita" audience="admin"/>
<topicref href="basic-security.dita" audience="enduser"/>
      

An enterprise software company, for example, can publish "Starter," "Professional," and "Enterprise" editions of their documentation from a single master map with conditional attributes. Each edition automatically includes only the relevant topics.

Collection Types

DITA maps support different collection types that define how topics relate to each other:

• Family Collections: Topics that are siblings in the hierarchy link to each other. Useful for FAQ sections where each question links to related questions.
• Sequence Collections: Topics follow a logical order with "next/previous" navigation. Ideal for step-by-step procedures that span multiple topics, reducing user confusion and improving task completion.
• Choice Collections: Topics represent alternative approaches to the same goal. Useful for different installation methods for various operating systems.