This case study shows how Scriptorium Publishing created the free DITA learning website LearningDITA.com 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, LearningDITA.de.
Develop multilingual training websites with open-source tools
1. Developing training websites
in multiple languages with
(mostly) open-source tools
Alan Pringle
Scriptorium Publishing
Tina Meißner
parson AG
Duck photos from pixabay.com unless otherwise specified
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
4. 4
Tina Meißner
Technical writer at parson AG
tekom traineeship in technical writing
Started learning DITA while
localizing learningDITA.com
Diploma in physics,
University of Potsdam
9. Combines (mostly) open-source tools
DITA learning and training specialization
GitHub
Video
WordPress
Extensible Stylesheet Language Transformations
(XSLT)
… and then adapted for German
11. 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
12. 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>
13. 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 <context> element, add a
<steps> element. </cmd>
<stepxmp>
<pre><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="my_first_task">
...
</context>
<ph outputclass="newchanged"> <steps>
</steps></ph>
</taskbody>
</task></pre>
</stepxmp>
...
</step>
14. 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><steps></lcItem>
<lcMatchingItem>Inside the <taskbody> element</lcMatchingItem>
</lcMatchingPair>
<lcMatchingPair>
<lcItem><step></lcItem>
<lcMatchingItem>Inside the <steps> element</lcMatchingItem>
</lcMatchingPair>
<lcMatchingPair>
<lcItem><cmd></lcItem>
<lcMatchingItem>Inside the <step> element</lcMatchingItem>
</lcMatchingPair>
...
</lcMatchTable>
</lcMatching>
</lcInteraction>
15. Test questions: true/false
<lcInteraction>
<lcTrueFalse id="true_false_command">
<lcQuestion>The <info> element is valid in any position inside the <step>
element.</lcQuestion>
<lcAnswerOptionGroup id="lcAnswerOptionGroup_nmw_q5b_kt">
<lcAnswerOption>
<lcAnswerContent>True</lcAnswerContent>
</lcAnswerOption>
<lcAnswerOption>
<lcAnswerContent>False</lcAnswerContent>
<lcCorrectResponse/>
</lcAnswerOption>
</lcAnswerOptionGroup>
<lcFeedbackIncorrect>The <info> element is only valid after the <cmd>
element inside the <step> element.</lcFeedbackIncorrect>
</lcTrueFalse>
</lcInteraction>
16. 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>
18. 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
tiny.cc/github_learningdita
21. 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
23. 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
25. 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
32. 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
33. 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
?
34. 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
?
35. 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
36. 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>
37. 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
39. 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
40. 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
41. 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)?
42. 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
43. 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
45. 45
Setting up LearningDITA.de
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”
46. 46
Filling the website with content
Further localizations
HTML contents
Explanatory texts that come with the plugin
Implemented transformation in oXygen XML
editor
47. 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
50. 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
51. 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”>
53. 53
Next steps
Solve formatting problems by adapting the
transformation
Localize videos
Provide German reference websites
Define change process
55. 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.
59. Contact us
Alan Pringle: asp@scriptorium.com
Tina Meißner: tina.meissner@parson-europe.com
LearningDITA.com team:
experts@learningdita.com
LearningDITA.de team: kontakt@learningdita.de
60. 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?
61. 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
http://dita05.honestly.de
or scan the QR code
The feedback tool will be available even after the conference!