Optimizing your DITA Content Model          for Translation            Amber Swope         DITA Strategies, Inc.
About the Speaker • Over 20 years of experience in the industry at   multiple companies of varying sizes and   industries ...
Process overview                                                  3                                                       ...
DITA knowledge poll                                                41.      Have implemented DITA and sent content through...
DITA overview                                             5• Darwin Information Typing Architecture (DITA)• Modular, struc...
6                                        DITA translation support Know what                                        Best ...
DITA translation support                                          7 Attributes that you can specify on each instance of a...
@translate attribute                                                8 Indicates whether the content of the element should...
@xml:lang attribute                                                9 Specifies the language of the element content. Valu...
@dir attribute                                             10 Specifies the directionality of text. Values:        ltr ...
Best practices                                             11 Update files only with changed text Translate reused or co...
Goals                                         12 Avoid translators changing elements Automate formatting with language-s...
13                                        Use @translate attribute on an Indicate                                element ...
Use @translate attribute on an element                                       14 Pro: can control translation for each ins...
Identify specific elements to not be translated                                       15 Pro: can globally indicate that ...
Non-translated element example                                       16copyright DITA Strategies, Inc. 2012
17                                        Elements to use Use                                        Glossary element su...
Elements to use                                              18 <menucascade><uicontrol> for menu option selection <fn> ...
Glossary support                                              19 Glossary topic provides full definition of term, includi...
Glossary usage                                             201. Define all information for a term in glossary topic in   s...
Glossary example                                              21 Glossary topic Concept topic Generated outputcopyright...
22                                        Guidelines Remove                                        Element usage ambigui...
Guidelines                                           23Avoid                                           Instead Using the ...
Element usage                                                    24Content purpose                        Ambiguous       ...
Single purpose for elements                                        25 Guidelines        Be reasonable – find the balance...
Manual formatting to avoid                                       26 Quotation marks Table headings Titles Terms Label...
Specialization versus @outputclass attribute                                       27 Specialization   Allows you to cre...
Specialization versus @outputclass attribute                                       28Specialize element                   ...
Specialization considerations                                       29 When authors must have control over processing, su...
Specialization examples                                            30 Sidebar support to provide sidebars for articles S...
31                                        Definitions Avoid                                        Referencing issues in...
Definitions                                            32 Content references allow you to directly reuse or include  elem...
Referencing issues                                               33 Article agreement of reused words or phrases        ...
References best practices                                       34Reference                                   Do not refer...
Strategies                                           35 Consider including the article in the reference Avoid using refe...
Summary                                                  36                                                             Re...
Resources                                           37 OASIS DITA Translation Subcommittee   “Best Practice for Managing...
Questions                                               38                                         <dita strategies>      ...
Upcoming SlideShare
Loading in …5
×

Optimizing your DITA content model for translation

1,102 views

Published on

Amber Swope's presentation at LavaCon 2012 in Portland, OR

0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,102
On SlideShare
0
From Embeds
0
Number of Embeds
38
Actions
Shares
0
Downloads
19
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide
  • 0:00 – 0:03
  • 0:04 – 0:04
  • 0:05 – 0:05
  • 0:06 – 0:07
  • 0:08 – 0:08
  • 0:09 – 0:09
  • 0:10 – 0:10
  • 0:11 – 0:11
  • 0:12 – 0:12
  • 0:13 – 0:14
  • 0:15 – 0:16
  • 0:17 – 0:17
  • 0:18 – 0:18
  • 0:19 – 0:19
  • 0:20 – 0:20
  • 0:21 – 0:21
  • 0:22 – 0:22
  • 0:23 – 0:25
  • 0:26 – 0:27
  • 0:28 – 0:29
  • 0:30 – 0:30
  • 0:30 – 0:31
  • 0:32 – 0:33
  • 0:34 – 0:35
  • 0:36 – 0:36
  • 0:37 – 0:37
  • 0:38 – 0:39
  • 0:40 – 0:40
  • 0:41 – 0:42
  • 0:43 – 0:43
  • 0:44 – 0:44
  • 0:45 – 0:45
  • 0:46 – 0:46
  • 0:47 – 0:47
  • 0:48 – 0:49
  • 0:50 – 0:50
  • 0:40– 0:40
  • Optimizing your DITA content model for translation

    1. 1. Optimizing your DITA Content Model for Translation Amber Swope DITA Strategies, Inc.
    2. 2. About the Speaker • Over 20 years of experience in the industry at multiple companies of varying sizes and industries • Author of numerous papers/presentations on information development and information architecture, including the “DITA Maturity Model” with Michael Priestley
    3. 3. Process overview 3 Remove Indicate Use Avoid inlineKnow what ambiguity when to appropriate content or DITA from translate DITA key provides content content elements references modelcopyright DITA Strategies, Inc. 2012
    4. 4. DITA knowledge poll 41. Have implemented DITA and sent content through multiple rounds of translation2. Have implemented DITA and sent content through first translation3. Have implemented DITA but not yet sent content through first translation4. Have some theoretical DITA knowledge, but no implementation experience5. Know what the acronym meanscopyright DITA Strategies, Inc. 2012
    5. 5. DITA overview 5• Darwin Information Typing Architecture (DITA)• Modular, structured, XML framework based on a topic-based architecture• Open-source standard approved and supported by OASIS• Implemented by companies in many industries around the worldcopyright DITA Strategies, Inc. 2012
    6. 6. 6  DITA translation support Know what  Best practices DITA providescopyright DITA Strategies, Inc. 2012
    7. 7. DITA translation support 7 Attributes that you can specify on each instance of an element @translate attribute @xml:lang attribute @dir attributecopyright DITA Strategies, Inc. 2012
    8. 8. @translate attribute 8 Indicates whether the content of the element should be translated or not. Default value is “yes”. Example:copyright DITA Strategies, Inc. 2012
    9. 9. @xml:lang attribute 9 Specifies the language of the element content. Values are from W3C (http://www.w3.org/TR/REC-xml/) Example:copyright DITA Strategies, Inc. 2012
    10. 10. @dir attribute 10 Specifies the directionality of text. Values:  ltr – left-to-right (processing default)  rtl – right-to-left Example:copyright DITA Strategies, Inc. 2012
    11. 11. Best practices 11 Update files only with changed text Translate reused or common content first Provide translations for generated output Provide full source language text for verification Use language-specific stylesheetscopyright DITA Strategies, Inc. 2012
    12. 12. Goals 12 Avoid translators changing elements Automate formatting with language-specific stylesheetscopyright DITA Strategies, Inc. 2012
    13. 13. 13  Use @translate attribute on an Indicate element when to  Identify specific elements to not be translate translated contentcopyright DITA Strategies, Inc. 2012
    14. 14. Use @translate attribute on an element 14 Pro: can control translation for each instance of an element Con: must specify for each instance of an element Common elements for which to indicate translation:  <term>  <ph>  <keyword>  <q> Examplecopyright DITA Strategies, Inc. 2012
    15. 15. Identify specific elements to not be translated 15 Pro: can globally indicate that content is not be translated Con: no flexibility Elements that are not usually translated:  All elements in the programming domain (<codeblock>, <codeph>, <parmname>,…) because they present code, which is usually in English  <tm> because trademarks are not usually translatedcopyright DITA Strategies, Inc. 2012
    16. 16. Non-translated element example 16copyright DITA Strategies, Inc. 2012
    17. 17. 17  Elements to use Use  Glossary element support for appropriate alternative forms of a word or phrase DITA elementscopyright DITA Strategies, Inc. 2012
    18. 18. Elements to use 18 <menucascade><uicontrol> for menu option selection <fn> for footnotes <note> with appropriate @type attribute value <prereq> for prerequisites Any element for which you generate a labelcopyright DITA Strategies, Inc. 2012
    19. 19. Glossary support 19 Glossary topic provides full definition of term, including alternatives for the primary term defined in the <glossterm> element The alternatives are nested within the <glossAlt> element:  <glossAbbreviation> – abbreviated form of the primary term  <glossShortForm> – shorter alternative to the primary term  <glossAcronym> – acronym for the primary term  <glossSurfaceForm> – proper presentation for first instance of term in output Reference glossary content with the <term> or <abbreviated-form> element using key referencingcopyright DITA Strategies, Inc. 2012
    20. 20. Glossary usage 201. Define all information for a term in glossary topic in source language2. Create key reference to the glossary topic that defines the term.  If you want to reuse the primary term, use the <term> element  If you want to reuse an acronym or the surface form, use the <abbreviated-form> element3. Translate all elements in the glossary topic as applicable in each target language; leave empty all inapplicable elements.The DITA-OT processing resolves the <abbreviated-form>element to the <glossterm> element if <glossAcronym> and<glossSurfaceForm> are empty.copyright DITA Strategies, Inc. 2012
    21. 21. Glossary example 21 Glossary topic Concept topic Generated outputcopyright DITA Strategies, Inc. 2012
    22. 22. 22  Guidelines Remove  Element usage ambiguity  Single purpose for each element from  Manual formatting content  Specialization or @outputclass model attributecopyright DITA Strategies, Inc. 2012
    23. 23. Guidelines 23Avoid Instead Using the formatting elements  Use element that identifies the Using an element for multiple content purposes  Clearly indicate the proper Typing formatting, such as usage for each element quotation marks  Use proper element and update Adding unnecessary formatting stylesheets that processing can handle  Specialize to create elements if Relying on @outputclass necessary attribute values for element identificationcopyright DITA Strategies, Inc. 2012
    24. 24. Element usage 24Content purpose Ambiguous ClearUser interface item <b> <uicontrol>Citation of resource <i> or “…” <cite>Presentation of new term <i> <term>Quotation “…” <q> or <lq>Directory path <codeph> or <ph> <filepath>copyright DITA Strategies, Inc. 2012
    25. 25. Single purpose for elements 25 Guidelines  Be reasonable – find the balance between clarity and complexity  Use elements for their intended purpose  Clearly define usage for content authors Examples  <filepath> – if the formatting for directory paths and file names is the same, then use for both purposes  <pre> versus <codeblock> versus <screen> versus <systemoutput> – if formatting is same, the use <codeblock>copyright DITA Strategies, Inc. 2012
    26. 26. Manual formatting to avoid 26 Quotation marks Table headings Titles Terms Labelscopyright DITA Strategies, Inc. 2012
    27. 27. Specialization versus @outputclass attribute 27 Specialization  Allows you to create new element types and attributes that are explicitly and formally derived from existing types  Provides selectable elements or attributes for authors @outputclass attribute  Names a role that the element is playing  Used primarily to provide styling instructions during generationcopyright DITA Strategies, Inc. 2012
    28. 28. Specialization versus @outputclass attribute 28Specialize element Use @outputclass No DITA element properly  You need to indicate a variation identifies the content on output formatting for Authors need to use frequently existing element and consistently  Expert needs to use Authors must specify usage infrequently  You can incorporate into templates (no author specification)copyright DITA Strategies, Inc. 2012
    29. 29. Specialization considerations 29 When authors must have control over processing, such as collapsible/expandable substeps When authors must manually type a valuecopyright DITA Strategies, Inc. 2012
    30. 30. Specialization examples 30 Sidebar support to provide sidebars for articles Specific table types to support consistency Collapsible/expandable elements to allow authors to control display Emphasis element to eliminate <b> or <i> usage Foreign word to identify non-translated foreign words Custom list structures to support consistencycopyright DITA Strategies, Inc. 2012
    31. 31. 31  Definitions Avoid  Referencing issues inline  Best practices content or  Strategies key referencescopyright DITA Strategies, Inc. 2012
    32. 32. Definitions 32 Content references allow you to directly reuse or include elements into topics Key references allow you to indirectly reuse content (like a placeholder)copyright DITA Strategies, Inc. 2012
    33. 33. Referencing issues 33 Article agreement of reused words or phrases  Gender  Singular v. plural Capitalization  First word in a sentence  Expansion of abbreviated forms Inflection in translated content  Word changes by role in sentencecopyright DITA Strategies, Inc. 2012
    34. 34. References best practices 34Reference Do not reference Complete units of content  Common nouns  Block elements  Translated text  Full sentences Non-translated text Proper nouns (when subject of sentence)copyright DITA Strategies, Inc. 2012
    35. 35. Strategies 35 Consider including the article in the reference Avoid using references as the first word in a sentence For commands, do not include the noun  No:  Yes:copyright DITA Strategies, Inc. 2012
    36. 36. Summary 36 Remove Indicate Use Avoid inlineKnow what ambiguity when to appropriate content or DITA from translate DITA key provides content content elements references modelcopyright DITA Strategies, Inc. 2012
    37. 37. Resources 37 OASIS DITA Translation Subcommittee  “Best Practice for Managing Acronyms and Abbreviations in DITA”  “Translation Best Practice for Leveraging Translation Memory”  “Best Practice for Indexing DITA Topics for Translation”  “Best Practice for Using the DITA CONREF Attribute for Translation” http://dita.xml.org/wiki/optimizing-dita-for- translationscopyright DITA Strategies, Inc. 2012
    38. 38. Questions 38 <dita strategies> amber@ditastrategies .com 503.922.3038copyright DITA Strategies, Inc. 2012

    ×