1. DITA Best Practices
Alan Houser
Principal Consultant and Trainer
Tel: 412-363-3481
arh@groupwellesley.com
Group Wellesley, Inc. www.groupwellesley.com

2. About Me
• Consultant and Trainer in Publishing Tools and
Technologies
• Member OASIS DITA Technical Committee
• Society for Technical Communication, Liaison to the
World Wide Web Consortium (W3C)
• Fellow, Society for Technical Communication
• Candidate for Vice President, Society for Technical
Communication, 2011-2012

3. DITA in Context
• Developed by IBM corporation as a
successor/replacement for IBMIDDoc (a “book-centric”
information model).
• Donated by IBM to OASIS (Organization for the
Advancement of Structured Information Standards).
• DITA 1.0 finalized by DITA Technical Committee February
2005, formally approved by OASIS June 2005.
• DITA 1.1 approved by OASIS August 2007.
• DITA 1.2 approved by OASIS December 2011.

4. Best Practices for Discussion
• Start with audience and task analysis
• Write for re-use
• Embrace minimalist principles
• Include human editorial control in your workflow
• Use best practices when migrating legacy content
• Manage boilerplate content and string replacement
values

5. First Rule of Technical Communication
???

6. First Rule of Technical Communication
Know your audience!

7. Best Practice #1: Start with careful
analysis of your audience and tasks
Many people are first exposed to DITA through the
standard topic types of task, concept, and reference.
They are tempted to begin by writing topics.
Any DITA scenario should begin with a careful audience
and task analysis.
Formalize the analysis in a DITA map.
Then write topics to populate the map.

8. Techniques for Audience and Task
Analysis
Persona
• Short description of a typical reader.
• Can be several sentences, typically a paragraph or two.
• Your audience is probably not “anybody”, even if you
think it is.
• For most products and services, 3 – 5 personas are
sufficient

9. Example Persona
John is a an administrator at a regional hospital. He
has 2 years of college, and is proficient with Microsoft
Office products. Once/month, he uses the Acme2010
Audit Software to generate a report of hospital bed
usage. He does not use Acme2010 Audit Software at
any other time, for any other task.

10. Techniques for Audience and Task
Analysis
Task Analysis: One Technique
Card sorting
• “Brainstorm” to discover typical user tasks.
• Write each task on a note card.
• Sort the note cards. Categories should reveal
themselves.
• Use the cards to define your topics.
• Use the categories and organization to define
your map.

11. Best Practice #2: Write for Reuse
Tip: Omit details except when necessary, especially when
details may vary across related products.
Examples:
Remove the five cover screws.
Remove the cover screws.
Enter your password on the backlit keyboard.
Enter your password.
Press the green button to start a call.

12. Best Practice #2: Write for Reuse
Tip: Avoid inline cross-references. Use DITA relationship
tables to generate list of related topics.
Example:
Learn about video in Playing Video on your Cell Phone.
What if you generate content for a model that does not
support video? The link is broken or suppressed.
Learn about video in .

13. Best Practice #3: Embrace Minimalist
Principles
• Roots of DITA:
minimalist
approach

14. Best Practice #3: Embrace Minimalist
Principles
Tip: A DITA topic should express a single idea, and be
usable stand-alone.
Tip: DITA does not support stem sentences. They are
considered unnecessary in topic-oriented publishing.

15. Best Practice #3: Embrace Minimalist
Principles
Stem Sentences
Changing your battery
To change your battery, you should do the following:
1. Remove the cover.
2. Remove the battery.

16. Best Practice #3: Embrace Minimalist
Principles
Stem Sentences
Changing your battery
1. Remove the cover.
2. Remove the battery.

17. Best Practice #3: Embrace Minimalist
Principles
Tip: Use the DITA <shortdesc> element to describe your
topic, to aid user navigation and improve findability.
The <shortdesc> element appears after the <title> and
before the <body> content. It is considered both content
and metadata. It should be a short (1-2 sentence)
description of the topic.
The <shortdesc> text is rendered as preview and hover-
over text.

18. Best Practice #4: Don’t forget editorial
quality control
A well-defined quality-control process becomes even more
important in the context of distributed topic-oriented
authoring. Be sure to include the review of human
editors and reviewers in your workflow.

19. Best Practice #5: When starting, put
aside legacy content
It is natural to want to begin a DITA migration by converting
legacy content to DITA.
If you take this approach, the result is the same legacy
content, with only a subset of DITA benefits.
Go to your legacy content only after you have completed
an audience and task analysis, and have developed your
DITA information architecture.

20. Best Practice #6: Manage reusable
content chunks
Tip: Maintain boilerplate text and variable string
replacements in special-purpose topics.
Examples:
• Admonishments (notes, cautions, warnings)
• Legal text
• Variable string substitution

21. Best Practice #6: Manage reusable
content chunks
Tip: DITA referencing, inclusion, and linking is based on
<filename> and <id>. Unlike most XML-based publishing
architectures, <id> values need not be unique across
document sets. Use this feature to label reusable chunks
of content.

22. Best Practice #6: Manage reusable
content chunks
Tip: Use DITA conrefs or conkeyrefs to maintain variable
text.
Tip: Use DITA filtering attributes to control replacement
text.

23. Best Practice #6: Manage reusable
content chunks
Tip: Use DITA 1.2 keyrefs to ease maintainability of
references (conrefs, topicrefs) and improve the authoring
experience.
<ph conref=“reusableText/variables_nokia.xml#Brand” />
<ph conref=“Phone/Brand” />

24. Contact Us!
We hope you enjoyed this presentation. Please feel free to
contact us:
Alan Houser
arh@groupwellesley.com
Group Wellesley, Inc.
933 Wellesley Road
Pittsburgh, PA 15206
USA
412-363-3481
www.groupwellesley.com