Creating a New DITA Project in Oxygen XML Editor

In an earlier blog post, I got my first taste of Darwin Information Typing Architecture (DITA). I learned to use the Oxygen XML Editor to import a Microsoft Word file and create a DITA project. Oxygen's conversion tool interpreted the headings in the document and split the content into a series of DITA topic files. Oxygen also used the headings to create a DITAMAP that neatly organized the document's topics.

However, the content I was importing was not designed with DITA in mind. In a good DITA file, complex instructions should be chunked down into smaller instructions. I didn't chunk down the lecture data beforehand. And while a standard lecture might move freely from idea to idea, a good DITA file strictly organizes core concepts, task data, and reference data.

In my most recent blog entry, I described how to create XML data in the Oxygen XML Editor. This time, I'll create some DITA following from the previous subject: the parts of a car. For specificity's sake, I'm working from the context of one specific car (my 2012 Toyota Prius) and one specific task: replacing the water pump assembly.

I want to create three DITA pages first, then create a DITAMAP that organizes them.

First I'll create a topic for the concept of a water pump assembly. I'll select File, New, then open the DITA folder in the template options to find the Concept template. I'll type "Water Pump Assembly: Concept" for the title, choose a filename, and hit the Create button. The DITA folder I just accessed also has templates for Task and Reference as well, so I quickly use the same procedure to make two more DITA files for those topics.

Since I started from templates, each of the topics I created provide some typical tags used by each topic type. For a concept topic, the Oxygen template prepares options for the <shortdesc> short description and the <conbody> concept body. For a task topic, there is the <taskbody> tag, which likely includes <step> tags and <cmd> tags for the steps of a procedure. A reference topic might include tags that are used for the presentation of tabular data, for example.

I'll begin to add data to the three files I created. For reference, I've found a few very useful websites. First is Toyota's part page for the water pump in my car. I found a diagram of the specific water pump assembly, as well as the product number and info about related parts.

This terrific water pump replacement writeup by Larry Carley on aa1car.com offers a great starting point to work from as I develop my version of the steps for this topic. I need to know how to perform this general task on my specific car. After some searching, I found a YouTube video that demonstrates the replacement of the specific water pump assembly. I also spent a lot of time digging through the Oxygen manual to figure out how to format DITA tags properly.

In creating these files, I found that it was not helpful to write DITA code in an IDE and copy/paste into Oxygen. It's easier to add each tag one by one in the composition pane. To create a table for the data in the reference topic, I used the menu to select DITA, Table, Insert Table. I created a <simpletable> element with three rows and three columns.

As I organized the content I'd assembled for these topics, I noticed that some of the individual steps in Carley's writeup were fairly long. The first instruction is to drain the radiator, which is a complex task that may require its own set of instructions. For now, I'll leave these instructions complex, and I can begin to chunk them later.