DITA at OASIS: Understanding
the Global Enterprise Challenge
JoAnn T. Hackos
President
Comtech Services Inc.
April 2, 2009
© 2009 Comtech Services, Inc.
1– 1
Management challenges
How do we handle it all?
© 2009 Comtech Services, Inc.
1– 2
DITA OASIS response
• Organization for the
Advancement of
Structured Information
Standards
• Darwin Information Typing
Architecture (DITA)
Technical Committee
• DITA Adoption Technical
Committee
• DITA Translation
Subcommittee
• And many other industryspecific groups
© 2009 Comtech Services, Inc.
1– 3
DITA includes Best Practices
• OASIS DITA Translation
Subcommittee
•
•
•
•
•
•
•
•
Comtech
IBM
MaxPrograms
XML International
Cisco Systems
PTC
SDL
And others
© 2009 Comtech Services, Inc.
• Committee documents
• Segmentation rules
• Content reference
management
• Multi-language
publications
• Indexing
• Acronyms and
abbreviations (coming)
• Glossary management
(coming)
• Legacy translation
memory
1– 4
Segmentation rules
• When you send topics for translation, the localization
vendor transforms the text into a form ready for the
translator
• Your text is split into blocks of text
• Blocks of text can be further segmented into
sentences
• Translation tools working with XML split segments by
working with the xml tags
• Most inline elements should be ignored by the
segmentation rules so that they don’t break text into
awkward sentence parts
• Best practice suggests that you think carefully about
your xml tagging so that you don’t create awkward
breaks
© 2009 Comtech Services, Inc.
1– 5
Segmentation example
• Good structure – Do this!
<p>Here is a list of the ingredients to mix:</p>
<ul>
<li>2 tablespoons peanut butter</li>
<li>2 tablespoons soy sauce</li>
<li>juice of 2 limes</li>
</ul>
<p>Mix thoroughly until all lumps are removed</p>
• A list separated from the paragraph will be
simple to translate
© 2009 Comtech Services, Inc.
1– 6
Segmentation example
• Poor design – Don’t do this!
<p>Here is a list of the ingredients to mix:
<ul>
<li>2 tablespoons peanut butter</li>
<li>2 tablespoons soy sauce</li>
<li>juice of 2 limes</li>
</ul>
Mix thoroughly until all lumps are removed</p>
© 2009 Comtech Services, Inc.
1– 7
Content reference
management
• Avoid using conrefs for
single word substitution
• Substituting single
words can lead to
awkward and
ungrammatical
translations
• Use conrefs for entire
sentences or blocks of
text
© 2009 Comtech Services, Inc.
In this example, the Note is an
independent block of text.
…
• </steps>
• <result>The call is
ended</result>
• <postreq>
• <note
conref=”reuse.dita#reusablep
hrases/hangup”/>
• </postreq> …
1– 8
Conref management
• To avoid grammar problems in the translation,
place conref’ed terms in the nominative case
• Do not use:
<p>Driving the <keyword conref=”models.dita#ford/FordFocus”/> is
an exhilarating experience.</p>
• Rather use:
<p>The <keyword conref=”models.dita#ford/FordFocus”/> provides
an exhilarating driving experience.</p>
© 2009 Comtech Services, Inc.
1– 9
Indexing
• Place index items carefully to avoid
creating segments that are difficult
to translate
• Place in the topic prolog metadata
• Place at the beginning of a block,
immediately following the start tag
• Add the <sort-as> tag for Asian
translations
© 2009 Comtech Services, Inc.
1– 10
Indexing example
© 2009 Comtech Services, Inc.
1– 11
Multi-language documents
• Many documents
require more than
one language, often
on the same page of
text, i.e., copyright
notices
• Manuals are often
issued with separate
sections for each
language
© 2009 Comtech Services, Inc.
• Place each language in
a separate languagespecific DITA topic
• Conref each language
into place into a final
topic
• Use DITA maps to
create each language
version and include in
“master” maps
1– 12
Acronyms and abbreviations
• DITA 1.2
specification
includes special
XML tags for
acronyms and
abbreviations
• Accommodates
translation
requirements
© 2009 Comtech Services, Inc.
Define the acronym in your DITA acronym
topic
<glossentry id="abs">
<glossterm>Anti-lock Braking
System</glossterm>
<glossBody>
<glossSurfaceForm>Anti-lock Braking
System (ABS)</glossSurfaceForm>
<glossAlt>
<glossAcronym>ABS/glossAcronym>
</glossAlt>
</glossBody></glossentry>
1– 13
Set up the acronym
• You then declare a key for
the acronym using the
standard DITA 1.2 keyref
mechanism:
• <map> ...
• <topicref
href="maintcar.dita"/> ...
• <glossref keys="abs"
href="antiLockBrake.dita"/>
• ... key declarations for other
referenced acronyms ...
• </map>
© 2009 Comtech Services, Inc.
• You can then refer to the
acronym using the standard
DITA 1.2 keyref mechanism:
• <task id="maintcar"> ...
• <info>The <abbreviated-form
keyref="abs"/> will prevent
the car from skidding ...
• </info> ...</task>
1– 14
Glossary management
• Create DITA
glossary topics
to manage
terminology and
to produce
glossary output
© 2009 Comtech Services, Inc.
<glossEntry id=”nbsp">
<glossterm>non-breaking space</glossterm>
<glossdef>A space that is not allowed to break across a
line of text.</glossdef>
<glossBody>
<glossPartOfSpeech value="noun"/>
<glossUsage>Do not provide in upper case (as in NBSP")
because that suggests a trademark
.</glossUsage>
<glossAlt>
<glossAcronym>nbsp</glossAcronym>
<glossUsage>Expand the acronym on first
occurrence.</glossUsage> </glossAlt>
<glossAlt id=”permspace">
<glossSynonym>permanent space</glossSynonym>
<glossStatus value="prohibited"/>
<glossUsage>This is a colloquial term.</glossUsage>
</glossAlt>
</glossBody> </glossEntry>
1– 15
Legacy translation memory
• Preserve as much of
your legacy
translation memory
as possible
• Set the
segmentation rule to
the sentence rather
than the block
© 2009 Comtech Services, Inc.
• Apply the TM to the
restructured DITA
content at the
sentence level
• Reset your TM to the
block level (if
preferred)
1– 16
If you follow the best
practices…
• “We saw translation costs reduced by 95% on
families of content with extensive reuse.”
• For example, taking a topic-based, familyapproach reduced the number of topics from 715
to 13.
• “We produced the Russian version of our
quick reference card in less than 20 minutes.”
• The sales manager was flabbergasted.
© 2009 Comtech Services, Inc.
1– 17
For more information
• Find links to the DITA Translation Best
Practices
http://dita.xml.org/wiki/optimizing-dita-fortranslations
© 2009 Comtech Services, Inc.
1– 18