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

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 time to rethink some technical writing practices that are outdated and not recommended today.

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 Do we really need all that glue?

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. How to do it with DITA.

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. Why bother with hangovers from the 19th century? 


Please add your own myths about tech writing here. 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