Just the facts: DITA References in Oxygen

DITA is a powerful tool for technical writers, especially those who need to maintain content that might be used across different products or projects. DITA provides several topic types that you can use to reuse and remix information in new ways to create different kinds of outputs. I've reviewed two of these topic types in previous articles: The DITA Concept file captures definitions and descriptions, and the DITA Task file describes the steps to complete a task or process.

Another topic type is the DITA Reference. Reference files contain just the facts about something. As a result, References can only contain limited information such as tables.

DITA References in Oxygen

I like to use the Oxygen XML Editor to manage DITA projects. To create a new DITA Reference file in the Oxygen XML Editor, start by right-clicking on the folder where you want to keep the new DITA file:

In the pop-up menu that appears, scroll down to find the DITA section. Expand that, and find Reference. Enter the title for the topic, and double check the filename that Oxygen will suggest for the new file:

Finally, click the Create button to start editing the new DITA Reference file. Oxygen will place you into the editor where you can work on your file and add new content:

Creating a data table

DITA Reference files are meant to be just the facts. You shouldn't include images, screenshots, installation steps, or other "about the product" information in the Reference file. Rather, the Reference file should be a listing of facts. This is usually a list, such as a table.

Let's add a data table for a made-up mobile phone. To add a table, hit Enter in the refbody field, and add a list. You can select options for the table before creating it, or you can modify the table later:

In this case, I've added a simple 3-row, 2-column table to demonstrate how to add a table in a Reference file. Your table might be much longer. For this example, I've made up some information for an imaginary mobile phone called the "Px a6" phone:

I've also added a comment at the end, but that doesn't actually do anything. Comments in DITA files are great for the technical writer who must manage a project full of DITA files. However, the comment are not displayed in the final transformation:

Just the facts

DITA References are a valuable part of the DITA ecosystem; with a DITA Reference file, you can capture just the facts about a product or a task. Use them to contain tables and other key product information. If you need to display plain information such as product specifications, operating ranges, software compatibility, supported platforms, or similar data, use the DITA Reference file.