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.
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
Richard Hamilton
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.
Sarah O'Keefe
There’s no such thing as a “good” tomato in my world. Unless, of course, you’ve turned them into salsa, ketchup, or tomato sauce.
Charles Cantrell
Ah! A woman after my own heart. The only good tomato is one that has been stewed and seasoned beyond recognition.
Al
#2 – it’s as if we could suddenly hear the screams of DITA specialists around the world all cry out in terror …
Sarah O'Keefe
Is that what that noise was??
Nancy Thompson
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!
Sarah O'Keefe
I think you can totally reuse the “thou shalt not” theme. As far as I know, nobody has filed a copyright/trademark on it recently…
techwriterkai
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… 🙂
Sarah O'Keefe
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.
Jean Kaplansky
Thank you especially for nos. 2, 3, and 6.
I expect you may hear from the cult of DITA regarding impending holy wars, though! 😉
Edwin
Verily I say unto you. Thou ain’t whistling Dixie.
I especially love #2. DITA is threatening to become crack cocaine for TWs.
SV
I need to learn XML, DiTA. Please can you refer where I can do so.
Alan Pringle
LearningDITA.com is a good place to start.