Let’s start with a definition: DITA is the abbreviation for “Darwin Information Typing Architecture”, hence the acronym. From a more practical point of view, DITA is an open XML standard that is designed to convey information in “chunks”, called topics, which are assembled at document level using “maps” (a table of contents). It is then possible to produce content in a variety of formats, including HTML and PDF. In recent years, DITA XML has become a popular means that many companies are using to meet their documentation needs more effectively. Like all forms of structured writing, it requires a different approach and thought process on the part of the writer than an “ordinary” document written in a linear fashion.

The history of DITA will be covered in another post, but if you are a technical writer or technical writer manager and want to move from your current process to DITA, you’ve come to the right place.

“Writing in DITA” is very different from linear or monolithic writing. As it is XML, writing in DITA means that you have to think and write in a structured way. One of the best examples to refer to is how to deal with everyday tasks. You focus on a subject, segment it and deal with it.

What follows is based on some real-life raw examples that we have dealt with (and then restructured). An unstructured writing topic can start with a few steps, then add an explanation, possibly a few more steps, talk about another process that needs to be considered, and then include the few remaining steps to complete the topic.
Next, mention the essential piece of information you needed to know from the outset that would have helped you decide whether you should do this task in the first place.

Okay, this may sound silly

OK, this may sound silly, yet we have often seen this kind of thinking process. This kind of approach reflects the linear thought processes of the author, who starts with a few steps then realises that you need some context, adds more steps, realises that in a slightly different case you would have to do something else, and then adds the remaining steps. He then finds that it is sufficient to do all this procedure in a specific circumstance, which is specified at the end.

This is an extreme example, but one that is not uncommon in our experience. One of the things that a structured approach to writing teaches the writer is to organise all this information in such a way as to present the information in such a way that the end user has all the cards in his hand when he needs them.
Thus, a structured approach will first provide context on the “how” and “why” of the procedure, make links to similar but related information or procedures, and then list the steps sequentially, inserting “notes” to provide additional context if necessary.

The tawny is released from its cage

If a significant change occurs at the end of the procedure (e.g. the Graphic User Interface changes to a new window, the machine is switched off, the tawny is released from its cage, etc.), the machine is switched off. ), the editor can add the expected result at the end of the procedure. In the end, you get a condensed topic that conveys all the information a user needs to know about that particular procedure. The topic is “stand alone” and can be presented in a stand-alone brochure or a “large manual”, as required.

This brings us to one of the main advantages of structured redaction in general

This brings us to one of the main advantages of structured writing in general, which is reuse: by designing a stand-alone procedure for a given situation, you automatically perpetuate it for reuse in other documents. When done well, it reduces the chore of the writer (or more likely another writer) having to rewrite the same procedure, with the added benefit of increased productivity (which is something that technical writers love).

Reuse is one of the pillars of the usual return on investment (ROI) for moving from a DITA unstructured writing approach. Reuse is implicit with DITA, although getting the most out of it is a different challenge (often, but not always, involving a content management system (CMS)).