DITA, Structured Writing and Reuse

Let’s get the definitions out of the way first: DITA is short for “Darwin Information Typing Architecture”, hence the acronym. This is not so much a definition of what DITA is, it is more a description of what the acronym stands. From a more practical standpoint, DITA is an open XML standard which is designed to convey information in bite-sized “chunks” known as topics, which are assembled together at the book-level using “maps”, which is then used to produce content in a variety of formats including HTML and PDF. In recent years DITA XML has become a popular way that many firms have been using to more efficiently tackle their documentation needs. Like all forms of structured writing, it requires a different approach and thought process on behalf of the writer as opposed to a “regular”, linearly-written document.

There will be more on the history and background of DITA in future posts, but if you are Technical Writer or a Manager of Technical Writers looking to make the switch from your current process to DITA, you have come to the right place.

“Doing DITA” is very different than writing typical, linear-style writing. Being XML, writing in DITA means that you need to think as well as write in a structured manner. One of the best examples I can think of has to do with how to deal with tasks, which is a particular topic type in DITA.

The following is based on some actual rough examples I have seen (and then had to re-structure). An unstructured task topic might begin with a couple of steps, then throw in an explanation, maybe a couple more steps, talk about another process that needs to be considered, and then include the remaining few steps to complete the topic. Then mention the critical piece of information you needed to know at the outset which would have told you whether you needed to do this task in the first place. Okay, this might seem daft, but I have seen people write tasks this way. This sort of approach mirrors the linear thought processes of the author, who starts out with a few steps, realizes that some background is needed, adds more steps, has another realization that in a slightly different case you would need to do something else, then adds the remaining steps. Then afterwards realizes that you only need to do this whole procedure under a specific circumstance, which is spelled out at the end.

This is an extreme example, but not uncommon in my experience. One of the things that a structured writing approach teaches the writer is to organize all of this information in a way that presents the information that end-user needs to know when they need to know it. So a structured approach would first provide some context on the “how” and “why” of the procedure, link to similar but related information or procedures, and then sequentially list the steps, inserting “notes” to provide extra context where needed. If there is a significant change at the end of the procedure (i.e. the GUI changes to a new window,  the machine is powered down, the gorilla is let of the cage, etc) the writer can optionally add the expected outcome at the end of the procedure. In the end you have an encapsulated topic that conveys all of the information that a user would need to know about that particular procedure. It is for all intents and purposes “self-contained”, and could be presented as a stand-alone pamphlet as well within a large manual depending on need. So we get to one of the main advantages of structured writing in general, which is re-use: by devising a self-contained procedure for a given situation, you automatically open it up for reuse in other documents. When done right, it reduces the drudgery of the writer (or more likely, another writer) having to write the same procedure over again, with the added benefit of increased productivity (which is something technical writing managers like).

Reuse is one of the pillars of the usual Return on Investment (ROI) for moving from an unstructured writing approach to moving to DITA. Reuse is implicit in DITA, though getting the most out of it is a different challenge (often, but not always involving a Content Management System (CMS)).

More to come…