Writing with Legos
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 Map is a Document
If the list includes both major and minor topics, the minor topics can be indented, or nested, under the major topics
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!
<title>Nimble AMS Help</title>
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.
The Map is a Topic
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.
It’s Morphin Time!
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!)
Then, when you are ready for more, check out the thoughtful and thorough Developing Quality Technical Information: A Handbook for Writers and Editors