Developing training websites in multiple languages

by Alan Pringle, Scriptorium , Tina Meißner on November 21, 2016

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.

DITA, which stands for Darwin Information Typing Architecture, is an open XML-based standard for creating, organizing, and managing content. The LearningDITA websites use multiple approaches to educate students about DITA. Lessons include step-by-step instructions, guided and independent exercises, and assessment questions. Courses also provide resources, such as links to instructional videos.

Managing source content and video

The LearningDITA project is created as DITA XML files. The DITA learning and training specialization provides specific structures for training content (for example, lesson objectives and test questions). The LearningDITA source content includes conceptual information, step-by-step instructions, exercises, and quiz questions.

For file storage, Scriptorium chose GitHub, a web-based repository based on the open-source Git version control system. With a free GitHub account, authors from all over the world can contribute and revise content in the LearningDITA repository.

Anyone can download the open-source files from GitHub and adapt the content for their own purposes.

In addition to source control, GitHub provides a project wiki. In the LearningDITA project, the wiki provides editorial and content development guidelines. The guidelines promote consistency in the source files.

The video content in courses is not part of the DITA source. Instead, we record and edit video clips with Adobe Captivate. Although we could have used an open-source tool to create the video content, we already had a license for Captivate. We post the videos to YouTube, the free video hosting service. YouTube provides a no-cost alternative to the challenges of hosting and maintaining video content on your own web server.

https://www.youtube.com/watch?v=1zVA2Spuy_c

Creating the LearningDITA.com site

Scriptorium already had experience with WordPress, an open-source system for managing and publishing web content, so we decided to publish LearningDITA.com as a WordPress-based site. We identified a learning management system (LMS) that integrates into WordPress. The LMS is a commercial system with a small licensing fee, but it supported our major requirements, including interactive quizzes and management of student accounts. There was no business justification to spend time and money creating our own LMS in WordPress when we could buy an inexpensive tool.

Scriptorium developed a process that transforms the DITA XML files into WordPress-compatible XML. This solution was based on the DITA Open Toolkit, a collection of open-source technologies that convert DITA XML into HTML, PDF, and other formats. We built an Extensible Stylesheet Language Transformations (XSLT) stylesheet in the toolkit to convert DITA XML into WordPress-compatible XML. We imported the transformed XML content into WordPress, made some minor manual adjustments in the LMS to ensure that test questions are associated with the right lessons, and published the course.

Localizing the DITA content

To localize the course files created in DITA, parson downloaded the English files from the GitHub project and copied them. We kept the structure of DITA elements and replaced the textual content inside the elements with the German translation.

The LearningDITA courses provide a large number of code snippets that are embedded in step-by-step instructions. Users can follow the instructions and compare their result with a sample solution presented in an associated DITA sample file. parson localized the sample files to match the code snippets in the instructions. We also localized the id attributes and the file names of the sample files. This does not cause any problems because the sample files are not referenced by DITA maps or topics. In addition, we replaced screenshots of the sample solution that were taken in the visual mode of an XML editor.

parson also needed to decide whether to localize the file names of the course files. As they form part of the resulting URL, a German name is easier for German users. But that also implied adapting all topic references.

Finding the right DITA terms in German

Finding established equivalents for DITA terms was another difficult task. parson mostly used direct translations to describe the function of DITA elements in the text, such as paragraph = Absatz, note = Hinweis, and substeps = Teilschritte. If there was no established German translation, parson needed to create one; for example, Auswahltabelle for a choice table.

Another challenge was to find a compromise between comprehensibility (that is, using German translations) and recognition by users (that is, using Anglicisms). parson tried to avoid Anglicisms as much as possible. Nevertheless, we decided to keep frequently used, DITA-specific terms to make them easily recognizable. Examples are: (task) topic = (Task-)Topic, map = Map, and body = Body.

We also used the Anglicism if a term did not have a German equivalent and paraphrasing would have been too complicated or too long in the context. These were case-by-case decisions. For example, we translated “inline element” with Inline-Element to align it with the translation for “block element” (= Block-Element) because both terms are often mentioned in one breath.

Setting up the website LearningDITA.de

Scriptorium provided parson with a list of required WordPress plugins and settings for setting up LearningDITA.de, so a hosting agency could reproduce the structure and layout of the English website. parson changed colors and fonts according to the corporate design. We also adapted the logo by changing the colors and by localizing the text “learningDITA” to “DITA lernen.”

parson localized the HTML contents on the website (that is, all but the DITA course contents) and the explanatory texts that come with the plugins. The explanatory texts confirm input by users or indicate errors during registration, login, and so on.

We customized the transformation from DITA to WordPress-compatible XML by localizing auto-texts that are used by the transformation. We also implemented the transformation in our XML editor oXygen to enhance usability. We can now start the transformation directly from oXygen.

Legal requirements for websites differ from one country to another. In Germany, Austria, and Switzerland, websites must state the publishing organisation or person, including name, contact information, trade registry number, etc. parson added this information, commonly known as Impressum. We also localized the privacy policy (Datenschutz) according to German legislation.

Conclusions

Open-source solutions are free but often expensive in terms of effort. If a licensed add-on to an open-source solution does what you need, does it make more financial sense to use it instead of creating your own solution? Is it worth the development effort to completely automate a process if that process is used infrequently?
Do not make assumptions about the cloud-based services people use. For example, not everyone wants a Google account because of privacy concerns, and Google services are blocked in some locations.
When content is translated, be prepared for that process to uncover errors. Need a workflow to address them.
Try to balance between translating DITA terms and adopting the original terms. These decisions can depend on the amount and the kind of Anglicisms used in your language, and on your target group.
When thinking about what to localize (id attributes, file names), weigh the work you would have to put in against the benefit of the consistency.
Consider legal requirements for different countries.
Establish a change process for subsequent changes after publication. The content always lives longer than you think.