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

Alan PringleScriptorium Publishing

Tina Meißnerparson AG

Duck photos from pixabay.com unless otherwise specified

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 1997Twitter: @alanpringle

Alan Pringle

Twitter: @alanpringle

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

What is Learning DITA?

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

Combines (mostly) open-source tools

Combines (mostly) open-source tools

DITA learning and training specialization GitHub Video WordPress Extensible Stylesheet Language Transformations

(XSLT)

… and then adapted for German

DITA learning & training specialization

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

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>

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>

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>

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>

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>

Managing source content with GitHub

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

Managing source content with GitHub

tiny.cc/collaborate_github

Creating video

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

Distributing the content with WordPress

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

Transforming DITA into WordPress

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

The results

The results: video

The results: matching

The results: true/false

The results: pick any that apply

31

Linguistic challenges

© junce11 – Fotolia.com

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

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

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

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

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

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

38

Localizing the course contents

© Carola Schubbel – Fotolia.com

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

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

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

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 DateiLektion1/l_Concept_neu_Start.dita ... </cmd>

NOYES

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

44

Setting up LearningDITA.de

© mejn – Fotolia.com

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

Filling the website with content

Further localizations HTML contents Explanatory texts that come with the plugin

Implemented transformation in oXygen XML editor

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

49

Room for improvements

© merrimonc – Fotolia.com

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

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

52

Next steps

© phanuwatnandee – Fotolia.com

53

Next steps

Solve formatting problems by adapting the transformation

Localize videos Provide German reference websites Define change process

Conclusions

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.

Resources

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

Contact us

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

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?

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.deor scan the QR code

The feedback tool will be available even after the conference!