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.
Recommendation: Use authoring shells to when you need to change the structure or domain constitution of
default DTDs. See Eliot Kimber's tutorial on document type shells].
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.
Recommendation: Play it safe; leave the <prolog> for general-topic information.
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.