FAQ: The Map Architecture of DITA


The Map Architecture of DITA

Learn about DITA Maps and how you can use them to organize topics for different purposes.

What is a DITA map?

Maps let you organize topics that you want to build into an output web or PDF. You can also generate navigation files based on the map structure, and generate links that get added to the topics.

A map file references one or more DITA topic files using <topicref> elements. The <topicref> elements can be nested to reflect the desired hierarchical relationships of the topics. Map files need to have a file extension of .ditamap to be processed properly.

Maps should only be used to process topics in the same directory as the map, or in subdirectories of the map's directory. While you can still reference topics outside of that scope, you should use the scope attribute (set to peer or external) to let processes know that the targets are out of reach, and should not be processed or copied to the output directory.

The relationships defined in a map can be used to create a Table of Contents (TOC), aggregate topics into a PDF document, or create links between topics in output. Maps provide a way to express these relationships in a single common format that can be used for different outputs. You can identify differences (for example, a topic could be included in the online Table of Contents but not in the aggregated PDF) using a common set of attributes.

Typically a user assistance information component has maps for a task hierarchy, concept hierarchy, and reference hierarchy, plus a relationship table for describing how tasks, concepts, and reference topics relate to each other. It may also include a mixed hierarchy map to support sequential reading. All the maps should be derived from task analysis of user scenarios. You can use maplists to organize your maps, and choose how they get processed.

Parent topic: Frequently Asked Questions about DITA, the Darwin Information Typing Architecture

Why use maps?

Maps separate the context of your information deliverable from its content. In a typical HTML-based web site, any change to the appearance or navigation of the site typically means making updates to dozens or more individual HTML pages. DITA enables all the navigation (sequences, hierarchies, relationtions) to be managed from a DITA map, which allows authors to manage navigation from a single structure, and then generate new web pages as needed.

How does DITA map apply context to topics?

What does a DITA map example look like?

A small map example

A typical DITA map might look like this: <map title="Tasks">
<topichead navtitle="Installing"
audience="admin">
<topicmeta>
<shortdesc>Install products before
configuring or using them.</shortdesc>
<topicmeta>
<topicref href="installstorage.dita">
<topicref href="unscrewcover.dita"/>
<topicref href="insertdrive.dita"/>
<topicref href="replacecover.dita"/>
</topicref>
<topicref href="installwebserver.dita">
<topicref href="closeprograms.dita"/>
<topicref href="runsetup.dita"/>
<topicref href="restart.dita"/>
</topicref>
<topicref href="installdb.dita">
<topicref href="closeprograms.dita"/>
<topicref href="runsetup.dita"/>
<topicref href="restart.dita"/>
</topicref>
</topichead>
:
</map>

How do maps manage relationships between topics?