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

3.
Alan Pringle
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

5.
What is Learning DITA?

6.
What is Learning DITA?
 Free learning websites: LearningDITA.com and
LearningDITA.de
 Multiple approaches to learning
 Step-by-step instructions
 Exercises
 Tests
 Videos
 Course authors: volunteers

7.
Combines (mostly) open-source tools

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.
DITA learning & training specialization

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.
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.
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.
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.
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.
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.
Managing source content with GitHub

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
tiny.cc/github_learningdita

18.
Managing source content with GitHub
tiny.cc/collaborate_github

19.
Creating video

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.
Distributing the content with WordPress

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.
Transforming DITA into WordPress

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.
The results

26.
The results: video

27.
The results: matching

28.
The results: true/false

29.
The results: pick any that apply

30.
31
Linguistic challenges
© junce11 – Fotolia.com

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.
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.
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.
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.
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.
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.
38
Localizing the course contents
© Carola Schubbel – Fotolia.com

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.
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.
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.
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.
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.
44
Setting up LearningDITA.de
© mejn – Fotolia.com

44.
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”

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.
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.
49
Room for improvements
© merrimonc – Fotolia.com

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.
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.
52
Next steps
© phanuwatnandee – Fotolia.com

51.
53
Next steps
 Solve formatting problems by adapting the
transformation
 Localize videos
 Provide German reference websites
 Define change process

52.
Conclusions

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.
Resources

55.
Resources
 LearningDITA.com and LearningDITA.de
 Learning DITA GitHub project:
tiny.cc/github_learningdita
 Nicky Bleiel on GitHub:
tiny.cc/collaborate_github
 LearnDash WordPress LMS: learndash.com

56.
Contact us

57.
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

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.
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!