Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Developing training websites in multiple languages with (mostly) open-source tools


Published on

This case study shows how Scriptorium Publishing created the free DITA learning website by combining the DITA learning and training specialization, GitHub, XSLT, video, and WordPress—and how parson AG adapted those technologies to develop the German site,

Published in: Technology
  • Login to see the comments

Developing training websites in multiple languages with (mostly) open-source tools

  1. 1. Developing training websites in multiple languages with (mostly) open-source tools Alan Pringle Scriptorium Publishing Tina Meißner parson AG Duck photos from unless otherwise specified
  2. 2. Alan Pringle  Chief operating officer, Scriptorium Publishing  Coauthor, Content Strategy 101 and Technical Writing 101  Bachelor of Arts in English, Wake Forest University  In tech comm since 1990—and with Scriptorium since 1997 Twitter: @alanpringle
  3. 3. Alan Pringle Twitter: @alanpringle
  4. 4. 4 Tina Meißner  Technical writer at parson AG  tekom traineeship in technical writing  Started learning DITA while localizing  Diploma in physics, University of Potsdam
  5. 5. What is Learning DITA?
  6. 6. What is Learning DITA?  Free learning websites: and  Multiple approaches to learning  Step-by-step instructions  Exercises  Tests  Videos  Course authors: volunteers
  7. 7. Combines (mostly) open-source tools
  8. 8. Combines (mostly) open-source tools  DITA learning and training specialization  GitHub  Video  WordPress  Extensible Stylesheet Language Transformations (XSLT) … and then adapted for German
  9. 9. DITA learning & training specialization
  10. 10. DITA learning & training specialization  Source content: DITA XML files  With learning specialization, DITA offers structures for training content  Lesson objectives  Step-by-step instructions  Test questions
  11. 11. Lesson objectives <learningContentbody> <lcObjectives> <lcObjectivesGroup id="lcObjectivesGroup_ipl_14q_bt"> <lcObjective> Identify best practices for authoring task topics </lcObjective> <lcObjective> Show examples of best practices in a task topic </lcObjective> </lcObjectivesGroup> </lcObjectives> <lcDuration> <lcTime value="1"/> </lcDuration> <lcInstruction> <p>This lesson covers best practices for authoring task topics. You will learn about planning tasks, providing appropriate context for a task, using a reasonable number of steps, using substeps appropriately, and keeping an eye on opportunities for reuse.</p> </lcInstruction> </learningContentbody>
  12. 12. Step-by-step instruction <steps id="steps_urj_vdy_zs"> <step><cmd>Continue working in the file l_task_start.dita.</cmd> </step> <step><cmd>After the closing tag of the &lt;context> element, add a &lt;steps> element. </cmd> <stepxmp> <pre>&lt;?xml version="1.0" encoding="UTF-8"?> &lt;!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> &lt;task id="my_first_task"> ... &lt;/context> <ph outputclass="newchanged"> &lt;steps> &lt;/steps></ph> &lt;/taskbody> &lt;/task></pre> </stepxmp> ... </step>
  13. 13. Test questions: matching <lcInteraction> <lcMatching id="matching_choicetable"> <lcQuestion>Match the basic elements involved in creating steps with their required locations in a strict task.</lcQuestion> <lcMatchTable id="lcMatchTable_f2n_c5b_kt"> <lcMatchingPair> <lcItem>&lt;steps></lcItem> <lcMatchingItem>Inside the &lt;taskbody> element</lcMatchingItem> </lcMatchingPair> <lcMatchingPair> <lcItem>&lt;step></lcItem> <lcMatchingItem>Inside the &lt;steps> element</lcMatchingItem> </lcMatchingPair> <lcMatchingPair> <lcItem>&lt;cmd></lcItem> <lcMatchingItem>Inside the &lt;step> element</lcMatchingItem> </lcMatchingPair> ... </lcMatchTable> </lcMatching> </lcInteraction>
  14. 14. Test questions: true/false <lcInteraction> <lcTrueFalse id="true_false_command"> <lcQuestion>The &lt;info> element is valid in any position inside the &lt;step> element.</lcQuestion> <lcAnswerOptionGroup id="lcAnswerOptionGroup_nmw_q5b_kt"> <lcAnswerOption> <lcAnswerContent>True</lcAnswerContent> </lcAnswerOption> <lcAnswerOption> <lcAnswerContent>False</lcAnswerContent> <lcCorrectResponse/> </lcAnswerOption> </lcAnswerOptionGroup> <lcFeedbackIncorrect>The &lt;info> element is only valid after the &lt;cmd> element inside the &lt;step> element.</lcFeedbackIncorrect> </lcTrueFalse> </lcInteraction>
  15. 15. Test questions: pick any that apply <lcInteraction> <lcMultipleSelect id="multi_select_stexmp"> <lcQuestion>What are some common uses of step examples? (pick any that apply) </lcQuestion> <lcAnswerOptionGroup id="lcAnswerOptionGroup_wbr_gxb_kt"> <lcAnswerOption> <lcAnswerContent>Showing the result of completing a step.</lcAnswerContent> </lcAnswerOption> <lcAnswerOption> <lcAnswerContent>Providing a code sample explaining how to complete the step. </lcAnswerContent> <lcCorrectResponse/> </lcAnswerOption> <lcAnswerOption> <lcAnswerContent>Giving a textual explanation of how to complete the step. </lcAnswerContent> <lcCorrectResponse/> </lcAnswerOption> ... </lcAnswerOptionGroup> <lcFeedbackIncorrect>The step example is often used to provide code samples or textual information explaining how to complete the step.</lcFeedbackIncorrect> </lcMultipleSelect> </lcInteraction>
  16. 16. Managing source content with GitHub
  17. 17. Managing source content with GitHub  GitHub: web-based repository based on Git version control system  Free for open-source projects  Anyone can access source content (and adapt)  With free GitHub account, authors can contribute and revise content
  18. 18. Managing source content with GitHub
  19. 19. Creating video
  20. 20. Creating video  Adobe Captivate: not open source, but already had license and skills  YouTube: no cost, no maintenance video hosting  Requirements and cost/benefit analysis  Any need to keep tools all open source?  Any reason to host videos ourselves? NO NO
  21. 21. Distributing the content with WordPress
  22. 22. Distributing the content with WordPress  WordPress: open-source system for managing and publishing websites  LearnDash: learning management system (LMS) add-on for WordPress  Commercial system but inexpensive  Supported requirements, including interactive tests and account management  No business justification to create our own LMS
  23. 23. Transforming DITA into WordPress
  24. 24. Transforming DITA into WordPress  DITA XML–to–WordPress XML process  XSLT stylesheet transformation in the DITA Open Toolkit  Minor manual adjustments after import  Associate test questions with right lessons  Less than an hour of work per course
  25. 25. The results
  26. 26. The results: video
  27. 27. The results: matching
  28. 28. The results: true/false
  29. 29. The results: pick any that apply
  30. 30. 31 Linguistic challenges © junce11 –
  31. 31. 32  DITA terminology is based on the English language  Element names  Attribute names  Names of topic types  Names of reuse mechanisms Finding DITA terms in German
  32. 32. 33  Avoid Anglicisms to ensure comprehensibility  Problems with translations  Reduces recognition by users for DITA-specific terms  Topic = Thema  Map = Mappe  Some English terms do not have a (well-known) German equivalent  Frontmatter = Finding DITA terms in German ?
  33. 33. 34  Avoid Anglicisms to ensure comprehensibility  Problems with translations  Reduces recognition by users for DITA-specific terms  Topic = Thema  Map = Mappe  Some English terms do not have a (well-known) German equivalent  Frontmatter = Titelei  Backmatter = ? Finding DITA terms in German ?
  34. 34. 35  Find compromise between comprehensibility and recognition by users  For DITA-specific terms, use Anglicisms  Topic, Map, Concept, Task, Reference, Key  For terms without German equivalent, use Anglicisms or paraphrase  Frontmatter/backmatter: explain what they contain and avoid term by using <frontmatter>-Element and <backmatter>-Element  Use translations for all other DITA terms Terminological decisions
  35. 35. 36 Style of speech  English website  Casual, narrative  DITA element and attribute names are used as nouns  Works because names are comprehensible for English speakers <p> ... creating a simpletable with ... </p> <p>Use a topicref to include ... </p> <p>When resolving a conref, ... </p>
  36. 36. 37  German website  Element and attribute names must be translated or paraphrased  Example: “conref” (content reference)  = Inhaltsreferenz  = Element mit conref-Attribut    Style of speech gets more formal Style of speech
  37. 37. 38 Localizing the course contents © Carola Schubbel –
  38. 38. 39 Localizing the course contents  Generally kept the structure of DITA elements and only replaced textual contents  Sometimes added elements  To provide an English term in a <term> element  To split up one list item into two  Localized DITA auto-texts that are used by the transformation
  39. 39. 40 Handling reused contents  Courses about topic types are organized similarly and contain reused paragraphs, notes, etc.  Code snippets in step-by-step instructions must match corresponding sample files  Until now, course topics did not use DITA reuse mechanisms
  40. 40. 41 Handling reused contents PRO  Improves consistency  Avoids redundant translation work  Facilitates termino- logical work CONTRA  Difficult to change the DITA element structure  English files must be prepared for localization  Use a Translation Memory System (TMS)?
  41. 41. 42 Deciding what to localize  File and folder names  PRO: Easier to understand for German users  CONTRA: Cross-references must be adapted  Decision  Several hundred course topics  Few sample files, which are not referenced by maps <cmd>Make a copy of the file lesson1/l_new_concept_start.dita ... </cmd> <cmd>Kopieren Sie die Datei Lektion1/l_Concept_neu_Start.dita ... </cmd> NO YES
  42. 42. 43 Deciding what to localize  Values of id attributes in sample files <concept id="my_first_concept"> <title>Wild duck species</title> <conbody> <p>North American wild ducks belong to one of the following categories:</p> <concept id="mein_erstes_Concept-Topic"> <title>Wildentenarten</title> <conbody> <p>Nordamerikanische Wildenten gehören zu einer der folgenden Kategorien:</p> YES
  43. 43. 44 Setting up © mejn –
  44. 44. 45 Setting up  Scriptorium Publishing communicated WordPress plugins and settings  Hosting agency reproduced structure and layout of the English website  Changed fonts and colors according to corporate design of parson AG  Localized “learningDITA” to “DITA lernen”
  45. 45. 46 Filling the website with content  Further localizations  HTML contents  Explanatory texts that come with the plugin  Implemented transformation in oXygen XML editor
  46. 46. 47 Considering legal requirements  Added Impressum, which must be included in websites in Germany, Austria, and Switzerland  Contains information about publishing organization or person  Name and contact information  Trade registry number, etc.  Adapted privacy policy according to German legislation
  47. 47. 49 Room for improvements © merrimonc –
  48. 48. 50 Structural improvements  Provide overview of reused sample file content  Clean up file and folder structures  Improve consistency  In highlighting content: <b>, <i>, or <term>  In marking up file and folder names
  49. 49. 51 Technical improvements  Prepare <author> elements for translators  Set xml:lang attribute on all DITA maps <prolog> <author>Alan Pringle, Scriptorium</author> <author type=”translator”>Tina Meißner, parson AG </author> </prolog> <map xml:lang=”en-US”> <map xml:lang=”de-DE”>
  50. 50. 52 Next steps © phanuwatnandee –
  51. 51. 53 Next steps  Solve formatting problems by adapting the transformation  Localize videos  Provide German reference websites  Define change process
  52. 52. Conclusions
  53. 53. Conclusions  Open-source: free but expensive.  Don’t make assumptions about cloud services.  Translating content = uncovering errors.  Balance translating terms and adopting original.  Think about whether to localize file names, and so on.  Think about whether using a TMS could pay off.  Consider legal requirements of other countries.
  54. 54. Resources
  55. 55. Resources  and  Learning DITA GitHub project:  Nicky Bleiel on GitHub:  LearnDash WordPress LMS:
  56. 56. Contact us
  57. 57. Contact us  Alan Pringle:  Tina Meißner:  team:  team:
  58. 58. DITA Forum  8:45–9:30 DITA Customization: Create Your Own Flavor  9:45–10:30 From Custom XML to DITA  11:15–13:00 DITA Interoperability  14:45–15:30 DITA: The Road to Delivering Digital Content at Siemens Rail  16:15–17:00 Developing Training Websites in Multiple Languages with (Mostly) Open-Source Tools  17:15–18:00 DITA: A Big Decision: Custom XML versus XML Standards—or No XML at All?
  59. 59. Your opinion is important to us! Please tell us what you thought of the lecture. We look forward to your feedback via smartphone or tablet under or scan the QR code The feedback tool will be available even after the conference!