DITA by example: Reference files

DITA is a power tool for technical writers. If you write a lot of documents that require copying and pasting data from other documents, you're probably a good case for migrating your workload to DITA.

When writing in DITA, everything is a topic, an individual "nugget" of data about something. You usually work in one of three topic types: I've discussed DITA Concept and DITA Task files. The third is the DITA Reference file.

DITA Reference files contain just the facts about something. Because it's just raw data about something, the DITA <refbody> schema is limited to items that contain data, including lists, tables, syntax, and sections.

Sample DITA Reference file

If you're just getting started with DITA, use this sample DITA Reference file to see some of the information you can put in a Reference. This sample file contains a section with additional text - this might contain context about the product, for example. The Reference file also includes a table of product terminology, and a list of how you might use the product:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="refsample">
    <title>Sample Reference File</title>
    <shortdesc>Let's explore DITA Reference files with this sample file.</shortdesc>
    <refbody>
        <section id="section_h4d_w2g_nyb">
            <title>Here's a section</title>
            <p>If you need to describe just one thing, like a table of operating ranges or something
                like that, you can just enter that in the <markupname>refbody</markupname>. But if
                you need to provide additional information in the DITA Reference, consider creating
                a <markupname>section</markupname>.</p>
        </section>
        <table frame="all" rowsep="1" colsep="1" id="table_ah1_3fg_nyb">
            <title>Product terminology</title>
            <tgroup cols="2" align="center">
                <colspec colname="Number" colnum="1" colwidth="1*" align="center"/>
                <colspec colname="Value" colnum="2" colwidth="1*" align="center"/>
                <thead>
                    <row>
                        <entry>Number</entry>
                        <entry>Value</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>"One"</entry>
                        <entry>1.0</entry>
                    </row>
                    <row>
                        <entry>"Two"</entry>
                        <entry>2.0</entry>
                    </row>
                    <row>
                        <entry>"Three"</entry>
                        <entry>3.0</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <example id="example_m4l_qfg_nyb">How you might use the product:<ul id="ul_szv_5fg_nyb">
                <li>In the office</li>
                <li>At home</li>
                <li>On the go</li>
            </ul></example>
    </refbody>
</reference>

This DITA Reference was created in Oxygen XML Editor. One feature I love in Oxygen is how it constantly validates the file as you work on it, so you know immediately if you've managed to add something that isn't valid in the schema.

And here's what the DITA Reference looks like when transformed into a PDF document: