Your favorite DITA how-to articles

The OASIS Open Darwin Information Typing Architecture (DITA) is an XML documentation standard that aims to make it easy for technical writers to reuse and remix content to create new kinds of documents. If you copy and paste content between documents to make new kinds of documents, that's a great use case that DITA is designed to solve.

We shared many articles in 2023 about how to get started with DITA topic authoring. While you can use any editor to create and manage DITA content, most of these articles use the Oxygen XML Editor:

1. Solving the copy/paste problem with DITA topics

The key to topic based authoring is to separate each unit of information into its own topic. Look for natural divisions in the text to suggest where you can separate blocks of content into a separate topic. Document sections are one way to break apart documentation into separate topics. Also look for content that answers a particular question or provides a how-to. These are also good candidates to split a document into separate topics.

2. Manage DITA projects in Oxygen XML Editor

Converting to DITA and topic based authoring has been a major improvement to my workflow. Most of my DITA work has been in the Oxygen XML Editor. It's a great commercial system to manage DITA projects on Mac, Windows, and Linux. However, the tool has some usability quirks that may make it challenging for the first time user. In this article, Robin shares the steps to create a new project and start work using Oxygen.

3. DITA topics with Oxygen XML Editor

Oxygen XML Editor is a powerful cross platform tool to manage and edit XML based projects, such as projects using DITA. While Oxygen is flexible and provides many options to create and modify DITA topics, I find the tool has a few usability quirks that make it difficult for first time users. Here is my workflow to create a new DITA topic using Oxygen.

4. DITA Concept files in Oxygen

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. DITA Concept files are an excellent way to capture definitions and descriptions. Use this as a quick-start guide to create DITA Concepts using Oxygen.

5. DITA Task files in Oxygen

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. DITA Task files describe the steps to complete a task. Learn how to create DITA Tasks using the Oxygen XML Editor.

6. Just the facts: DITA References in Oxygen

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. If you need to capture plain data about something, use a DITA Reference file. Here's how to create a DITA Reference in Oxygen XML Editor.

7. Putting it all together with DITA Maps

Once your content is separated into these topic files, you can glue them together in any order to generate a variety of different outputs. The mechanism that connects these topics and arranges them in the right order is the DITA Map. Connect multiple DITA topics together using DITA Map to create different kinds of documents - all without copy/paste.