DITA Task files in Oxygen

Darwin Information Typing Architecture (DITA) is an open XML document format that is best used for information topics that can be reused and remixed to create larger documents. When working with DITA, divide each "nugget" of information into a topic file, and use tools to string multiple topics together to create a variety of different output types, like PDF documents, ebooks, and websites.

Concepts versus Tasks

DITA Concepts are one kind of DITA file. A Concept file describes a thing or process. But if you need to describe the steps of a process, you need a different DITA file: the DITA Task.

Let's say you worked for a toy company in Denmark that makes kits you can assemble from plastic bricks and other parts. For a kit like a firetruck, you might write a brief DITA Concept file to describe each part that goes into the kit: a 2×4 brick, a 2×2 brick, a set of wheels, a siren, a light, a winch. Each DITA Concept describes the thing.

You also need to describe the steps to put the kit together. The DITA Task file captures the instructions.

Later, you can combine the Concepts files and the Task file to create a full assembly guide for the kit. Note that the individual pieces in the kit will likely be used in other projects, too - with DITA, you document the Concepts once, then reuse them in any project that needs them.

DITA Task in Oxygen

I use the Oxygen XML Editor to edit DITA files. Oxygen is a very flexible XML editor with excellent support for all DITA file types. For this example, I've started with an empty project called DITA Example Project, with a single folder for my topics called Topics.

Right click on the Topics folder and use the context menu to select New > File.

You'll get a list of different file types you can create. Navigate down to DITA > Topics > Task.

Oxygen lets you fill in a few details about the DITA file before creating it. In this case, I wanted to create a sample DITA Task about how to pick up a cat.

Oxygen will automatically put you into the DITA editor, with the basic fields already filled in for you.

In the editor view, you can edit the DITA topic in a quasi-what you see is what you get mode. You'll still see controls and indicators that show your position in the DITA file, but the editor also displays text formatting more or less how it will appear in a finished document.

Enter the contents of your DITA Task. Note that the Task file type, like most DITA file types, has a title, short description, and a body. The Task also includes a context for the task, where you might provide background information about the task, including who should perform the task and on what schedule.

DITA files are just XML files. Click the Text tab at the bottom of the Oxygen editor window to edit the XML directly.

In the text view, you can see how the XML is arranged. Note that the DITA Task file contains a <title> section, <shortdesc> section, and a <taskbody> section. Every DITA topic contains a title, description, and body. The Task also has a <context> section where we provide the background information or context for doing the task. The procedural steps themselves go in a <steps> list, with each item in the list as a separate <step> with a <cmd> instruction.

Remember that DITA topics are just "nuggets" of information, and you combine these topics together into a larger document. But for this example, we can also transform the single DITA Task directly. This is what the Task looks like as a PDF: