Revision of Myths about technical writing from Thu, 2008-06-12 21:15

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?


Add your favorite technical writing myth to this page. Just log in and select the "Edit" tab above. Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I