Remixing content with DITA Maps

DITA is a powerful documentation tool that excels in use cases where you need to reuse and remix content to create new documents. If you often create new kinds of documents by copying and pasting from other documents, you can benefit by using DITA. With DITA, you create a separate topic file for each piece of information you need, then you use another XML file that connects everything into one document.

For example, let's say you were the technical writer for a new Linux distribution. "Tech Writer Live" is a made-up Linux distribution for this example, but assume it's a "live" Linux system that contains a ton of technical writing tools. Let's also say that this distribution comes in different "spins," where each spin provides the same tools but uses a different desktop system: GNOME, KDE, Xfce, and Cinnamon.

As the technical writer for this distribution, you might need to create user documentation for each spin. These user guides will likely share the same "about Tech Writer Live" description, but provide a unique description of each desktop. Further, you might need to create a single "master" document that contains a description of each spin as a separate section.

Topics as DITA Concept files

Writing these five documents (four spins plus one master document) using a traditional word processor will require copying and pasting content between documents: each user guide will reuse the same "about" description, and the master document will reuse the descriptions of each desktop spin. This requires careful tracking of each section of the documents, and re-copying any updated text.

But managing all this content becomes much simpler if you separate each unit of information into a separate DITA topic file. Let's use DITA Concept files for this example; a DITA Concept contains information about a thing or process. We will create five DITA Concept files, one for each topic:

1. The overall description of Tech Writer Live: about.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="about">
    <title>Tech Writer Live</title>
    <shortdesc>Tech Writer Live is a version of Linux loaded with tons of technical writing tools
        and applications.</shortdesc>
    <conbody>
        <p>Tech Writer Live is a "live" distribution of the Linux operating system. That means you
            can run it on any computer without actually installing it. This makes it easy to use
            Tech Writer Linux to boot any computer and immediately get to work. Tech Writer Linux
            comes in several versions or "spins," each with a different desktop experience: GNOME,
            KDE, Xfce, and Cinnamon.</p>
        <p>Tech Writer linux comes packed with technical writing tools and technologies, including
            Docbook, Markdown, LaTeX, DITA, HTML, LibreOffice, and more.</p>
    </conbody>
</concept>

2. The GNOME desktop: gnome.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="gnome">
    <title>GNOME</title>
    <shortdesc>GNOME is a modern, user friendly desktop that gets out of your way.</shortdesc>
    <conbody>
        <p>The GNOME desktop provides an easy to use graphical interface to Linux. Move your mouse
            to the "hot corner" in the upper left of the desktop to activate the application
            launcher. Once your program is running, GNOME fades into the background so you can focus
            on your work.</p>
    </conbody>
</concept>

3. The KDE desktop: kde.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="kde">
    <title>KDE</title>
    <shortdesc>KDE is a powerful and extensible graphical desktop for Linux.</shortdesc>
    <conbody>
        <p>The KDE desktop's sleek, modern appearance immediately lets you get to work. The KDE
            Plasma interface will be immediately familiar to many users. When you're not working on
            other tasks, the desktop widgets can show you information including the weather and
            calendar reminders. </p>
    </conbody>
</concept>

4. The Xfce desktop: xfce.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="xfce">
    <title>Xfce</title>
    <shortdesc>Xfce is a lightweight, standards-based desktop that runs well on a variety of
        systems.</shortdesc>
    <conbody>
        <p>The Xfce desktop aims to run fast on any system, even older computers with less memory
            and slower processors. Xfce's customizable interface is pleasant and uncomplicated,
            making it easy to focus on the tasks at hand without getting distracted with fancy
            window decorations.</p>
    </conbody>
</concept>

5. The Cinnamon desktop: cinnamon.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="cinnamon">
    <title>Cinnamon</title>
    <shortdesc>The Cinnamon desktop is a classic take on a modern graphical interface.</shortdesc>
    <conbody>
        <p>Cinnamon provides an advanced desktop with a classic user experience. Users should feel
            right at home with the traditional desktop metaphor with the task bar and application
            launcher. </p>
    </conbody>
</concept>

Each DITA Concept file provides information about just one topic. Keep each file focused on one topic; if you need to branch out to describe another topic, create another DITA Concept file for that topic.

Connect DITA files with DITA Maps

To combine several DITA Concept files into a single output document, connect them using a DITA Map. A Map file is an XML document that lists references to other files. How these references are arranged also defines the document structure: a reference to a single file creates a section, and nesting several references under a single topic reference creates subsections.

One way to combine these files is to define a DITA Map that defines a "master" document. In some organizations, a master document might be used by a sales team or a service center. The sales team typically uses a master document to reference all products sold by the company, and the service center usually has a copy of the master document to assist them with customer issues. In this example, we'll create a master document that uses the "about Tech Writer Live" description at the top, with subsections to describe each spin:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>About Tech Writer Live</title>
    <topicref href="about.dita">
        <topicref href="gnome.dita"/>
        <topicref href="kde.dita"/>
        <topicref href="xfce.dita"/>
        <topicref href="cinnamon.dita"/>
    </topicref>
</map>

Save this DITA Map as master.ditamap. The DITA Map references the about.dita file first, and nests the four spin descriptions as subsections. But the most important feature is that we didn't have to copy and paste content to make this document; we simply referenced the DITA Concept files we already had. We can generate a PDF copy of the documentation using the open source DITA OT command line tool. In DITA OT, the dita command will transform a DITA file into a variety of formats, such as PDF:

$ dita -i master.ditamap -f pdf

The generated master.pdf document will have a title page with the DITA Map's title, then a table of contents for each section, followed by a chapter or first-level section that describes Tech Writer Live, with each desktop spin in a subsection:

Remix content with a new DITA Map

With DITA, it's easy to remix and reuse our existing DITA Concept files to create four separate user guides, each containing a copy of the "about Tech Writer Live" section but with a separate description of the desktop spin. For each user guide, we need to write a new DITA Map that connects the DITA Concept files we want to include: about.dita and the DITA Concept file that describes the spin.

Here is a sample DITA Map file called guide_gnome.ditamap for the GNOME desktop spin. For this user guide, the DITA Concept files are listed individually, which will create each as a separate first-level section:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>Tech Writer Live (GNOME)</title>
    <topicref href="about.dita"/>
    <topicref href="gnome.dita"/>
</map>

When you process this DITA Map using the DITA OT command line tool, you will generate a new PDF called guide_gnome.pdf that contains a cover page with the DITA Map's title, then a table of contents, followed by the two sections of content.

$ dita -i guide_gnome.ditamap -f pdf

Content reuse with DITA Maps

You can use the same process to create user guides for the other three desktop spins: KDE, Xfce, and Cinnamon. Each guide will reuse the about.dita file but include a different file to describe the desktop: kde.dita, xfce.dita, or cinnamon.dita.

If you created each document using a traditional desktop word processor, you would need to copy and paste between documents. As you updated the "about Tech Writer Live" description in one document, you would also need to copy and paste the new text into each of the other files. Even for this small set of five documents (one master document plus four user guides) this can quickly become overwhelming.

But DITA makes it easy. With DITA, you can capture each topic in a separate DITA Concept file, and connect them together with a DITA Map.