DITA by example: Task files

DITA is a great way to reuse and remix content to create new kinds of documentation. If you often copy and paste material from other documents to create a new, custom document, then DITA might be a good fit for you.

To leverage DITA in a project, you should break up your document into individual topics, each providing specific information. For example, use a DITA Concept file to store information about a thing.

To describe a process, use a DITA Task. DITA Tasks start with a <context> section to provide brief background information about the task, including why users should perform the task, and what to expect from the task. Your steps to complete the process follow the context, in a <steps> section, with each step in a separate <step> block.

Sometimes, it helps to see an example file to compare the source to the final output. To demonstrate the most common elements of a DITA Task, I created these installation instructions that describe a made-up example about how to install a software program on your computer.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="install">
    <title>How to install the software</title>
    <shortdesc>Here's how to install the software on your computer.</shortdesc>
    <taskbody>
        <context>This is a made-up example about how to install a software program on your computer.
            (The <markupname>context</markupname> should provide a brief background about the task,
            why they should do the task, and what to expect from the task. This section should not
            replace a DITA <b>Concept</b> file.)
            <p>The software has an easy to use <i>installation wizard</i> that does most of the hard
                work for you. What you'll need:</p>
            <ul id="ul_d24_vll_kyb">
                <li><b>The installer.</b> Download the software installer from our website at <xref
                        href="https://www.example.com/" format="html" scope="external"
                        >www.example.com</xref></li>
                <li><b>Your license key.</b> The license key is unique to your username.</li>
            </ul>
            <p>When you are ready, follow these steps to install the software on a <tm tmtype="reg"
                    >Microsoft Windows</tm> computer:</p>
            <note id="note_mdz_44l_kyb">Installing the software takes about ten minutes on most
                computers.</note>
        </context>
        <steps>
            <step>
                <cmd>Start the installer by double-clicking the <cmdname>Setup</cmdname> program
                    icon.</cmd>
            </step>
            <step>
                <cmd>Select the destination folder for the software.</cmd>
                <info>By default, the destination folder will be
                    <filepath>C:\Program Files (x86)\The Software</filepath></info>
            </step>
            <step>
                <cmd>Click the <keyword>Ok</keyword> button.</cmd>
            </step>
        </steps>
        <postreq id="postreq_jr3_s4l_kyb">You will be prompted to enter your license key when you
            run the software for the first time.</postreq>
    </taskbody>
</task>

Like any DITA topic file, the DITA Task has this basic structure:

1. Title
2. Short description
3. Body

This sample DITA Task is a "cooked" example that exercises several common elements that you might use to describe a process. Note that this DITA Task includes <b> and <i> tags to highlight certain information; use these where you can't use a more appropriate DITA element.

The example also includes an unordered list <ul> with requirements before attempting the install, and a note to indicate the typical time to install the software. You'll also find examples for a registered trademark, extra information, and post-installation steps.

You can transform the DITA Task individually, or include it in a larger project using a DITAMap. Here is a sample PDF transformation of the single DITA Task, generated using Oxygen XML Editor: