The ten commandments of DITA

Sarah O'Keefe / Opinion13 Comments

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.

About the Author

Sarah O'Keefe


Content strategy consultant and founder of Scriptorium Publishing. Bilingual English-German, voracious reader, water sports, knitting, and college basketball (go Blue Devils!). Aversions to raw tomatoes, eggplant, and checked baggage.

13 Comments on “The ten commandments of DITA”

  1. Thou art truly a wise woman, Sarah (though I have doubts about your aversion to tomatoes. Have you tried homegrown, late-summer tomatoes, served with no dressing and at room temperature? If not, do so before you give up. Real tomatoes bear no resemblance to what you get in the grocery store:-).

    I especially appreciate the 2nd commandment, which has a corollary: Thou shalt not fit the task to the tool; pick tools that fit the task.

  2. #2 – it’s as if we could suddenly hear the screams of DITA specialists around the world all cry out in terror …

  3. It’s strange, but I’ve just been working up ideas for a presentation on the DITA heresies we successfully commit in our publication and translation environment. I was also planning to use the biblical “thou shalt not” theme, but you beat me to it — and addressed a higher level of commandments than I am formulating. Rats!

  4. And then there’s the corollary a/k/a commandment #11: “… and the same be true for similar denominations, such as structured writing, topic-based authoring.” Except for #6 which seems to be a DITA-specific quirk… 🙂

    1. An ecumenical #6 would be something like:

      “Thou shalt not overcomplicate thy toolset to demonstrate thy technological superiority over mere mortals.”

      I now await the 10 #techcomm commandments, ecumenical edition.

  5. Verily I say unto you. Thou ain’t whistling Dixie.
    I especially love #2. DITA is threatening to become crack cocaine for TWs.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.