Skip to main content
July 18, 2013

The ten commandments of DITA

Because the phrase “best practices” is boring, we provide, for your reading pleasure, the ten commandments of DITA.

1. Thou shalt not abuse thy tags.

Each DITA tag has a purpose. If your content doesn’t fit nicely into the DITA tag set, consider whether a) you can specialize and b) you are using the right content model. Speaking of which…

2. DITA is one way; it is not the only way.

DITA is one solution that works well for certain problems. It may not be right for your particular business problem.

3. Thy business case is thy guide through the wilderness.

You must build a business case so that you can justify your plan to executives, procurement, and the rest of the non–tech comm world.

4. Thou shalt not copy thy neighbor’s text.

DITA provides lots of options for reuse. Copying and pasting is not an acceptable choice when you have keyrefs, conrefs, topic-level reuse, and more. Reuse is good. Copying is bad.

Stone tablet version Thou shalt not copy they neighbor's text.

Texture: Patrick Hoesly (flickr)

5. Thou shalt not use phrase-level conditionals. They are displeasing to thy translator’s eye.

Phrase-level conditionals are tempting, but they lead to trouble when text is translated. Stick to sentences or (preferably) paragraphs for your conditional work.

6. Thou shalt not specialize to demonstrate thy technological superiority over other mortals.

Some situations require specialization, but this technique introduces additional complexity into a DITA implementation, so proceed with caution. The same is true for other complex techniques, like conkeyrefs. Be sure that you need specialization and aren’t just showing off.

7. Approach thy legacy content with caution, for it is unclean.

It is our experience that some legacy content is so troublesome to convert that it is easier to start over. Typically, this is content that:

  • Is not topic-based
  • Does not follow a style guide
  • Does not use consistent tags
  • Is not well-written

Before launching a massive (and expensive) conversion project, ask yourself whether the content is worth the investment.

8. Cast away the doubters and the naysayers: thine output can be beautiful.

Don’t mistake the sample output from the DITA Open Toolkit for the only possibilities. There are lots of ways to publish DITA, and you can achieve very attractive results (even for PDF using the Open Toolkit).

9. Choose thy CMS with care, for it is thy bedrock.

A poor CMS, or even an excellent CMS that is a poor fit for your requirements, will lead to trouble. Be very careful with your CMS evaluation process.

10. Help thy neighbors, for one day you will need thy neighbor’s help.

Participation in the DITA community, whether at conferences or in online groups, is well worth the time investment.