DITA Worst Practices Guide

This page is sponsored by the OASIS DITA Adoption Technical Committee and captures cases where teams involved in implementing DITA made a design decision that turned out to be painful in the long run. Technically, DITA can support both best-case and worst-case implementations.

A. Deployment / Technical Issues

Hacking Default DTDs

Modifying the out-of-the-box DTDs that ship with OASIS DITA is a high-risk decision. If you modify an out-of-the-box DTD without renaming it, you are breaking interoperability with peer groups using DITA and causing upgrade problems whenever you attempt to move to a new release of DITA.

Adding Index Terms to Topic Prologs

Topic <prolog>s are useful locations for authoring metadata that applies to the entire topics. The <prolog> is a good location for most <indexterm> instances, for example. If you remove <prolog> from your topics, you are forced to place general-topic metadata such as <indexterm> entries inside elements such as <abstract> that were not designed to host general-topic metadata.

Putting Steps in Footnotes

Footnotes are not appropriate places for instructional step-wise text. Keep text in the <steps> tag in <task>.

B. Content Design Issues

Using <concept> for all content

The power of DITA is in topic typing. Keep with <task>, <concept>, and <reference>.

Embedded Procedures in Concept Topics

Adding an <ol> procedure to a concept topics.

Embedded Procedures in Footnotes

Adding an <ol> procedure to a footnote.


DITA_Worst_Practices (last edited 2015-07-27 16:03:05 by StanDoherty)