DITA Best Practices: Use the Maps, Folks.  Use the Maps.

​When you use a tool like Word™ to write a conventional document, the accepted approach is to pour in the content, sprinkling headings along the way, and then insert a table of contents widget to bubble up a hierarchical index of your content, based on the headings.

​DITA approaches documents from the other direction. First, create the table of contents (or ditamap) and then the content. Whenever you like, the editing tools can use the map to generate your document on demand.

Or documents. Plural.

DITA chunks your work into topics. Using maps, DITA lets you stack those clunks into as many documents as you like.

You can use a topic in multiple documents. You can use a topic in the same document multiple times, And you can render the same document in multiple formats, like webhelp, PDF, or even, (brrr) Word™.

The DITA map is deceptively simple. It starts out as a list of topics

<map>
<title>Committees</title>
<topicref href=”Overview.dita”>
<topicref href=”Committees-Objects.dita”/>
<topicref href=”Committees-Homepage.dita”/>
<topicref href=”Working-With-Committees.dita”>
</map>
If the list includes both major and minor topics, the minor topics can be indented, or nested, under the major topics

<topicref href=”Working-With-Committees.dita”>
<topicref href=”Creating-A-Committee.dita”>
<topicref href=”Detailed-Steps-For-Creating-A-Committee.dita”/>
</topicref>
</topicref>
We use this approach with Nimble AMS Help. The top-level help.ditamap references seven other ditamaps, which in turn reference other ditamaps and topics. If you click through the left sidebar, you can see the ditamaps in action!

​<map>
<title>Nimble AMS Help</title>
<topicref href=”support.ditamap”>
<topicref href=”success-guides.ditamap”/>
<topicref href=”self-service.ditamap”/>
<topicref href=”staff-view.ditamap”>
<topicref href=”developer-guides.ditamap”>
<topicref href=”all-workbooks.ditamap”>
<topicref href=”release-notes.ditamap”>
<topicref href=”Delivered.dita”>
</map>
Pro Tip – Many DITA editors will create new topics from a map (like a wiki), making it easy to write the outline first, and then create the topics.

​If some of the topics are already on another DITA map, you can reference a DITA map anywhere you can reference a topic.

<map>
<title>Success Guides</title>
<topicref href=”Success-Guide.dita”>
<topicref href=”ams-meets-crm.ditamap”/>
<topicref href=”committees.ditamap”/>
<topicref href=”reporting-and-analytics.ditamap”/>
</topicref>
</map>
In the context of a book, each chapter could have its own DITA map, listing the topics in that chapter, and then a map for the entire book can list just the maps for each chapter.

If you want to create an abridged version of a book, you can use another DITA map to cherry-pick the topics or maps you want to use in the shorter version. Later, you can update topics in one place, and regenerate the deliverables to bring out a revised edition of both the abridged and unabridged versions.

Most DITA editors let you drill down on a DITA map, so you can surf from the top-level maps down to the lowest-level topic, clickety-click.

​To create a deliverable (or document) with DITA, you can convert a DITA map, or single topic, to a desired format. The same map can be used to create web sites, PDFs, word documents, and more.

DITA itself is designed to be presentation neutral, and deliverables can be rendered with completely different styles, and share all or only some of the topics.

The topic headings are determined by how it is nested on the DITA map. A “H1” in one deliverable can be a “H2” or “H3” in another deliverable.

While responsive web sites are all the rage, you could also use DITA to easily generate multiple sites from the same content library using completely different styles.

For Nimble AMS, we generate a stand-alone PDF deliverable for our seasonal release notes, include the same content in the full web site, and then again in a full PDF version on the web site content. All three deliverables are generated automatically using our build server, TeamCity, from single-source content stored in Git.

For Agile documentation, you can create new topics as features are added, and use an updated map to transform new deliverables for your upcoming version. If a shared topic is updated, you can revise the topic in one place, and show the new copy in multiple deliverables.

Using the DITA “audience” feature you can target content within a topic for a group of readers, or for a specific version of a product. (A “feature switch” for content!)

​DITA maps are deceptively simple way to make it easy to both single-source deliverables in multiple formats, and reuse content between different deliverables. DITA maps encourage authors to think more about organizing and outlining content steams, and help authors turn rambling rivers of sludge into shiny streams of clean content.

​For more about DITA, a great starting point is DITA for the Impatient. Then snag yourself a demo of XMLMind XML Editor, oXygen XML Editor, or Easy DITA, and have at it!

Then, when you are ready for more, check out the thoughtful and thorough Developing Quality Technical Information: A Handbook for Writers and Editors

---

​Pro Tip – DITA is a great way to implement a Salesforce help site! Or build Agile documentation for your Scrum project, sprint by sprint.

---

​Ted Husted is a Kaizen Squad developer on the Nimble AMS product crew. “We make the good changes that create a great product.”