When you start working with DITA, there are some things that you may feel you need for traditional reasons that you won't find in DITA. Before you try to modify or specialize DITA, it may be worthwhile to rethink some technical writing practices that are outdated and not recommended today.

1. The GlueText Myth

Glue text is defined as transitional information intended to inform readers of what has come before or comes after a particular procedure, description, or explanation. In topic-oriented authoring, which forms the basis for the DITA Model, transitional text has become problematic. See Do we really need all that glue?

2. The Stem Sentences Myth

Stem sentences in technical communication have long been considered a standard practice to introduce new content, especially steps in a task. The task stem sentence, generally consisting of a partial sentence such as “To start the machine:” , followed by "1. Plug it in.", "2. Turn it on.," etc., is not supported by any explicit DITA element in the DITA Task information type. See How to do it with DITA.

3. The Front-Matter Page-Numbering Myth

Traditional books use lower-case Roman numerals for introductory front material. This and folio-style chapter numbering, page 2-35, are deprecated practices today. See Why bother with hangovers from the 19th century?

4. The Callouts on Graphics Myth

If you want to reuse the same graphic in multiple publications and even multiple languages, it is a good practice not to put callouts in the source file of the graphic itself. Instead, you place your callouts "on top of" your graphic in your text editor (Word) or DTP program (InDesign, FrameMaker, ...). This is not supported in DITA. Therefore, if you need to use callouts in graphics, try to use language-independent ones (A, B, C...) in the source file of the graphic and put the explanation of these callouts in a table below the graphic in your DITA XML content. [Yves Barbion]

 

 

Add your favorite technical writing myth to this page. Just log in and select the "Edit" tab above.