DITA Concept files in Oxygen

DITA is an open XML standard (Darwin Information Typing Architecture) that makes it easy to isolate parts of documentation that can be remixed with other projects. With DITA, the goal is to create units of information called topics.

Because DITA is a standard, you can find lots of tools that help you create DITA files and manage projects based on DITA. One tool I like is Oxygen XML Editor.

Concept files

A common topic is one that describes a thing or process. For example, if you work at a company that sells custom stationery kits, you probably need to ship a document with the kit that describes what is in it. Writing such a document using a word processor would require copying and pasting text between different documents to create a custom document.

One way to solve this is to write separate topics on the components that could go into each kit: a felt tip pen, a ballpoint pen, a fountain pen, a marker, and a pencil. Describing a thing is a typical use of a DITA Concept file. Concept files describe a thing or provide background information about a process. For the stationery kit example, every possible item you might include in the kit would be a new DITA Concept within a project: felttip.dita, ballpoint.dita, fountain.dita, marker.dita, and pencil.dita.

Create the file in Oxygen

Let's start with an example. First, start a new project in Oxygen. Right-click on a folder in the project, and select New - File in the contextual menu:

Next, you need to specify what kind of file to create. Oxygen supports lots of different file types - but in this example, we want to create a DITA Concept file. Navigate down the list of types and expand the DITA group, then Topics, and select Concept to create a new DITA Concept file.

When you create a new DITA topic file in Oxygen, you can assign a title and filename to the topic. For this example, enter Sample concept for the title; Oxygen will attempt to fill in a suitable filename such as sample_concept.dita.

Click the Create button to generate an empty DITA Concept file:

Edit the file in Oxygen

DITA files are just structured XML content without direct styling. The styling gets applied later when the DITA file or DITA project is transformed into a final product like a PDF document or a website. You can click the Text tab to view the DITA XML source as plain text:

Because DITA lacks direct styling, Oxygen's Author tab doesn't provide many style options. However, you can use the toolbar to apply certain formatting like bold, italics, underline, links, and different lists. Focus your writing to use the structures and formatting provided in DITA.

You don't have to use the menus or the toolbar to add new formatting. When you hit Enter on the keyboard, Oxygen will present a contextual menu of different options you can apply within the DITA file. The most common reason to press Enter is to start a new paragraph, so Oxygen makes that the default action (hit Enter again to start a new paragraph) but you can navigate the menu with the arrow keys to apply other formatting and apply styles.

Using DITA

DITA Concept files are an excellent way to capture definitions and descriptions. Every definition of a new thing or new process should go into a separate Concept file. 

By separating the topics into separate files, it becomes easier to reuse them to create new projects. Going back to the stationery kit example: If every custom order of a new bespoke stationery kit requires creating a one-off document that describes what's in the kit, you can remix the DITA Concepts for each item and create a new output document. We'll cover how to transform documents in a later article.