DITA by example: Concept files

Working with DITA requires a shift in how we write documentation. If you write materials and find that you reuse a lot of content from other documents, your workflow might be a good candidate for DITA.

Using DITA means breaking down your documentation into components or topics. Each topic goes into a separate file so you can use it again later. You generate a completed document by connecting several topic files. Concept files are one example of a DITA topic. DITA Concepts are self-contained files that describe a thing or a process.

At their core, DITA files are XML documents that use a well-defined structure. You can write these DITA files "by hand" in a plain text editor, but most professional technical writers use a tool to make their job easier. I use Oxygen XML Editor, which provides excellent DITA support.

When editing a DITA file in Oxygen or another DITA editor, you will likely spend most of your time in an "author" mode where you can focus on the text and not get distracted by the XML code.

I wanted to demonstrate what a DITA file looks like "under the hood." This sample Concept file demonstrates several common formatting types, such as basic formatting, lists, notes, code blocks, and photos. This XML document is a valid DITA Concept file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="Untitled">
    <title>Sample Concept File</title>
    <shortdesc>A few examples of what you can include in a DITA Concept file.</shortdesc>
    <conbody>
        <p>DITA <b>Concept</b> files describe a <i>thing</i> or a <i>process</i>. The Concept file
            should be self-contained and only describe the thing or process.</p>
        <p>Concept files can contain a variety of basic text formatting, including <b>bold</b>,
                <i>italics</i>, and <u>underline</u>. You can also include lists, such as to
            describe the characteristics of something:</p>
        <ol id="ol_srg_5gf_3yb">
                <li>This is an ordered list</li>
                <li>The second list item</li>
                <li>The third list item<ul id="ul_r3w_wgf_3yb">
                        <li>An unordered list within a list item</li>
                        <li>Another bullet item</li>
                    </ul></li>
            </ol>
            <note id="note_kmb_hgf_3yb">Do not include the <i>steps</i> to perform a process. That
                information should go into a DITA <b>Task</b> file.</note>
        <p>Concept files can also include inline code or code blocks, like this C program to print
                <tt>"Hello world"</tt>:</p>
        <codeblock id="codeblock_ywm_hhf_3yb" outputclass="language-c">#include &lt;stdio.h>
int main() {
  puts("Hello world!");
  return 0;
}</codeblock>
        <p>Concept files can also include images, such as diagrams or photos. Here is a photo of a
            cat: (CC0, from <cite>pexels.com</cite>)</p>
        <fig id="fig_mlj_djf_3yb">
            <title>Photo of a cat</title>
            <image href="../photos/cat-computer.jpg" width="66pc" id="image_nlj_djf_3yb">
                <alt>a cat sitting next to a computer, looking into the camera</alt>
            </image>
        </fig>
    </conbody>
</concept>

You can process this Concept file through a DITA tool like Oxygen to generate a finished document in different formats, including HTML websites, ebooks, and PDF files.

Use this sample Concept file as a demonstration of some of the powerful features in DITA. For more information about working with DITA files in Oxygen, I recommend Getting Started with DITA at the Oxygen website. The DITA file specification is an open standard; you can read more about it at OASIS DITA TC.