Wednesday, May 02, 2018

Translating your DITA Project

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Usually when working with a DITA-based project you can either store the project contents using a Content Management System (CMS) or some open-source version control system like Git or SVN. CMSs usually come with their own translation support so this blog post is mostly for end users who use Git or SVN to store and collaborate on their DITA project.

Choosing a Translation Agency

Ideally your translation agency should be able to handle DITA content directly, without you needing to convert the DITA to some intermediary format. This means that you will have the full benefit of DITA reuse features to minimize translation costs.

As a very important rule, if you plan to translate your project you should get in touch with a DITA-aware translation agency very early in your project's timeline. Reliable translation agencies that translate DITA content directly (for example WHP) usually need to have a preliminary discussion with you about how the project is structured, what terms need to be skipped when translating, how various measuring units are translated, content reuse, taxonomy, and the handling of screenshots that appear in your DITA content. So the way that you write your DITA content will be influenced by your discussion with the translation agency.

If your translation agency does not directly handle DITA content, there are commercial tools that can be used to convert DITA to XLiff: https://www.maxprograms.com/products/fluenta.html.

Optimizing Content for Translation

In general, there are three main principles to take into account when writing DITA content that will be translated at some point:
  1. Use a controlled vocabulary (usually the Simplified Technical English vocabulary).
  2. Avoid reusing inline elements other than product names. The following DITA Users List discussion describes the reasons for this: https://lists.oasis-open.org/archives/dita/201301/msg00029.html.
  3. Avoid profiling/filtering content at inline level. For the same reasons as (2).
You can read more about this in the following article: https://www.infomanagementcenter.com/publications/best-practices-newsletter/2010-best-practices-newsletter/successful-localization-in-dita/.

General DITA Project Structure

Usually you need to keep a folder that contains all your DITA maps/topics in English and have separate folders for other languages with equivalent DITA topics translated in that specific language. This article could be useful: http://www.ditatranslation.com/articles/organize_files.html.

General Translation Workflow

When translating DITA content, the most common process involves these steps:
  1. You create your content in the primary language using a DITA authoring tool (Oxygen XML Editor).
  2. Before each release, you gather all the DITA topics that have been changed and need to be translated. The Oxygen Translation Package Builder plugin might be handy for this.
  3. Send a copy of the relevant DITA files to the translation agency (known also as "localisation service provider").
  4. Receive translated DITA content back from the translation agency and integrate it in each language-specific project folder.

Publishing your Translated Content

All your translated DITA maps and topics should have the xml:lang attribute set with the appropriate value on the root element. Besides the actual translated content, the published output may contain various static texts like the word Table followed by the table number, Figure following by the number or Note which appears before each DITA <note> content. The DITA Open Toolkit has support for a number of languages for the HTML-based outputs and for the PDF-based outputs. But you can also add support for other languages: http://www.dita-ot.org/dev/topics/plugin-addgeneratedtext.html#ariaid-title1. There is also a specific topic which describes how to add a new language to the Oxygen-specific WebHelp Responsive output: https://www.oxygenxml.com/doc/versions/20.0/ug-editor/topics/localize-webhelp-responsive-new-lang.html.

Liability

So who is responsible for a bad translation that may produce damage to a client following a set of mis-translated steps? From my discussions with translation service providers, the translation agencies do not assume any liability for incorrectly translated content. Usually a company that needs to translate their DITA content in multiple languages has regional headquarters in various countries and somebody from the company's regional headquarters would be responsible to review and accept the translated content as appropriate.

This concludes my DITA translation overview. As we do not translate the Oxygen User's Manual in various languages, our internal knowledge of translating DITA content is quite limited so any feedback on this small article is welcomed.

Tuesday, March 27, 2018

Guided DITA Authoring Solution Overview

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

We've had past blog posts about how Oxygen can be used to impose various editing behaviors for your team. In this blog post, we are going to try to bring all of these solutions together in a comprehensive overview.

Learning to Work with DITA and Oxygen

You can find useful links for learning to edit DITA using Oxygen in this previous blog post: http://blog.oxygenxml.com/2016/03/resources-for-learning-dita-with-oxygen.html.

Migrating to DITA

There are multiple reasons why you would want to migrate from unstructured content to structured: http://blog.oxygenxml.com/2015/12/migrating-to-structured-standards-based.html.

This older blog post details some possibilities of migrating Word documents to DITA: http://blog.oxygenxml.com/2016/05/how-to-migrate-from-word-to-dita.html. You also have ways to migrate from XML-based standards (like DocBook or XHTML to DITA) using a set of predefined transformation scenarios.

Restricting the Visual Editing Experience

The entire visual editing experience using the Author editing mode in Oxygen is CSS driven. Oxygen has support for defining various CSS layers that can be applied when editing DITA content. For example, if you choose to create a Lightweight DITA topic in Oxygen, it has a special editing layer that allows it to be edited with a combination of buttons, hints, and form controls. This blog post details how a custom CSS used for editing can be created and shared with others:http://blog.oxygenxml.com/2016/10/customizing-dita-visual-editing.html.

Implementing Your own Style Guide

Let's say you are a team of technical writers collaborating on a DITA-based project and suppose that you have your own various best practices in regards to which elements to use and when to use them. So, at some point you gather a set of HTML resources that explain how various DITA elements should be used, you store them on an internal server, and you want all your team members to have access to that set of HTML resources directly from Oxygen. This blog post provides more details and useful links to help you get started: http://blog.oxygenxml.com/2016/03/implementing-your-own-style-guide.html

Imposing Controlled Attribute Values

If you want to impose DITA attribute values that need to be set for profiling or general use, this blog post should cover all you need to know about this: http://blog.oxygenxml.com/2015/07/controlled-attribute-values-for-your.html

Imposing Business Rules and Structure Restrictions to the DITA Content

In most cases, instead of relying on people to memorize numerous internal documentation style rules, you can convert many of these rules to Schematron and allow the application to automatically signal the content author when a rule is violated. You can also add quick fixes to show authors various ways to rectify the problem. This blog post contains more details about this: http://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html. The DITA framework can be extended in order to add new Schematron rules: http://blog.oxygenxml.com/2017/02/sharing-schematron-validation-rules.html.

Running Batch Validation Checks on all of Your DITA Content

The Validate and Check For Completeness tool available in the DITA Maps Manager view performs a lot of different consistency checks on all your DITA topics. It can also be used to apply Schematron business rules on all of your topics: http://blog.oxygenxml.com/2015/12/dita-map-validate-and-check-for.html.

Sharing DITA Editing Customizations with Your Team

Most of the custom editing behaviors, toolbar, and menu buttons that are available when editing DITA content are defined in the DITA framework configuration. A framework configuration's general anatomy is described here: http://blog.oxygenxml.com/2014/08/the-oxygen-sdk-part-2-frameworks.html.

The framework configuration can be shared with all of your team members. For example, here is a way to restrict team members from using certain DITA elements: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html. Furthermore, here is a way to distribute new DITA file templates to your team: http://blog.oxygenxml.com/2015/12/sharing-new-custom-file-templates-for.html.

Sharing Global Application Settings with Your Team

Let's say you want all of your team members to enable the automatic spell checker when writing documentation, or you want all of them to use a custom term dictionary or a custom set of learned words. This older blog post offers some hints about how global Oxygen settings can be distributed to your team members: http://blog.oxygenxml.com/2015/11/sharing-application-settings.html.

Collaboration, Content Management, and Version Tracking

All major Component Management Systems (CMSs) have plugins that can be installed in Oxygen to provide access to the CMS: https://www.oxygenxml.com/partners.html#cmssolutionpartners. Even if you lack the funds to buy a commercial CMS, there are still plenty of open source version tracking solutions that allow collaboration for a single DITA project: http://blog.oxygenxml.com/2013/12/collaboration-teams-working-on-common.html. For example, the Oxygen User's Manual is written in DITA and we use a GitHub private repository to collaborate on it: http://blog.oxygenxml.com/2014/11/collaboration-for-documenting-software.html.

Allowing Subject Matter Experts to Review Content

Many technical writers are interested in having their content reviewed by the subject matter experts who are directly involved in building the tools. Oxygen has support for change tracking and adding comments directly in the edited content. Subject matter experts do not necessarily need to have the standalone version of Oxygen installed. The Oxygen Web Author is an online editing and reviewing solution that allows them to add comments and propose changes directly in the DITA content by using any device with a web browser (laptop, tablet, phone): https://www.oxygenxml.com/xml_web_author.html.

I hope this overview will help you to implement a complete guided authoring experience using Oxygen. As usual, if you have any questions or suggestions, they are welcome.

DITA Publishing Customization Overview

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Oxygen XML Editor publishes DITA content to various output sources using a bundled version of the DITA Open Toolkit (short name: DITA OT) publishing engine. Oxygen versions prior to version 20 come with two DITA OT versions:
  • DITA OT 1.8 located in the OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT folder.
  • DITA OT 2.x located in the OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT2.x folder.
while Oxygen version 20 comes bundled only with DITA OT 2.x located in the folder specified above. You can find the exact version of DITA OT bundled with Oxygen by looking in the main menu Help->About at the Frameworks tab.

DITA Open Toolkit Overview

The DITA Open Toolkit is an open source publishing engine that can publish DITA content to various output sources such as XHTML, PDF, or Windows Help (CHM). Since it has a plugin-based architecture, it can be extended with extra plugins that either define new formats for conversion or customize an existing conversion format. You can run the DITA OT from Oxygen using its transformation scenarios or you can run it directly from a command line:http://www.dita-ot.org/dev/topics/building-output.html.

The DITA OT bundled with Oxygen contains more plugins than the standard DITA OT that can be downloaded from the DITA OT official web site. For example, it contains pre-installed plugins for converting DITA content to Word, EPUB, Oxygen WebHelp, or to publish to PDF using CSS to customize the output: http://blog.oxygenxml.com/2017/03/useful-dita-ot-plugins.html.

Publishing Customizations (Before you begin)

Some customizations, usually for HTML-based output, can be made simply by creating a custom CSS and they do not involve modifying the DITA OT engine in any way. But most customizations might involve adding a new plugin to the DITA OT. So here are some best practices before you begin your customization:
  1. Copy the bundled DITA OT folder (usually OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT2.x) to a location outside of Oxygen. This will allow you to have full write access to the folder in order to install new plugins:https://www.oxygenxml.com/doc/versions/20.0/ug-editor/topics/dita-ot-install-plugin.html.
  2. In the Oxygen Preferences->DITA page, set the default DITA OT distribution to be the external copied one. This will mean that Oxygen will use the external DITA OT for DITA validation and publishing. After doing this, you will be able to upgrade the Oxygen version and benefit from all editing-related improvements without affecting the publishing system.
  3. Share that external DITA OT copy with the rest of the team. If you are using a repository like Subversion or Git for collaboration, you can commit the entire modified DITA OT publishing engine as part of your project. This will allow everybody else in your team to use the official changes that you made for publishing an engine containing. This will also allow you to set up some kind of automatic publishing system using an open-source integration server like Travis.

Customizing the XHTML-based outputs

Usually XHTML-based outputs can be modified by using a custom CSS stylesheet to override various styles. If you edit an XHTML-based transformation scenario in Oxygen, there is a parameter called args.css that can be set to point to your custom CSS and a parameter called args.copy.css that can be set to yes to copy the CSS to the output folder. To know what CSS styles to override, you can use your web browser’s CSS Inspector tools to look at the produced HTML output. The same parameters can be set when publishing from a command line: http://www.dita-ot.org/dev/topics/html-customization-css.html.

You can also create plugins to customize the XHTML-based outputs by adding an extra XSLT stylesheet: for example, http://blog.oxygenxml.com/2013/12/creating-simple-dita-open-toolkit.html. A list with all DITA OT XSLT extension points can be found here: http://www.dita-ot.org/dev/extension-points/plugin-extension-points-xslt-import.html.

Customizing the Oxygen WebHelp-based output

Oxygen’s DITA OT comes bundled with specific plugins developed by Oxygen that allows publishing DITA content to WebHelp Classic and WebHelp Responsive outputs. Oxygen’s User’s Guide has detailed topics about how to customize these outputs: https://www.oxygenxml.com/doc/versions/20.0/ug-editor/topics/wh-responsive-customization-tips.html#wh-responsive-customization-tips.

Customizing the PDF Classic output

The DITA to PDF output can be customized either by creating a PDF customization folder (in this case the DITA OT folder will not be modified at all) or by creating a PDF customization plugin: https://www.oxygenxml.com/doc/versions/20.0/ug-editor/topics/dita-pdf-output.html. There is also a book called DITA For Print that contains details about how to customize various aspects.

Customizing the DITA + CSS to PDF output

In recent versions, Oxygen added a new transformation scenario called DITA Map PDF - WYSIWYG that allows you to use CSS to style the PDF output, lowering the required knowledge for implementing a PDF customization. There is an entire chapter in the Oxygen users manual covering various PDF customization details: https://www.oxygenxml.com/doc/versions/20.0/ug-editor/topics/dcpp_the_customization_css.html#dcpp_the_customization_css.

Thursday, January 25, 2018

Composing Author Actions

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Suppose that each time you insert a DITA table in the Author visual editing mode, you want to always have the attributes colsep="1" rowsep="1" frame="all" set on it. The purpose of this post is to create a new DITA-specific action for inserting a table that invokes the current table insertion action and then forces those three attributes to be set on the table element. Here are some steps to accomplish this:
  1. Follow the steps listed in this older blog post to create an extension of the DITA framework: http://blog.oxygenxml.com/2016/10/customizing-dita-visual-editing.html.

  2. In the Document Type Association preferences page, edit the DITA framework extension you just created. Go to the Author->Actions tab and create a new action with the ID change.table.colsep. Use the predefined ChangeAttributeOperation to set the (colsep="1" attribute) on the closest table element. The custom action would look like this:

  3. Based on the same idea, create two more new actions called "change.table.rowsep" and "change.table.frame" that will set the rowsep="1" and frame="all" attributes on the closest table, respectively.

  4. Create a new action with the ID insert.table.fixed.attributes and use the predefined ExecuteMultipleActionsOperation to call 4 actions in a row, the original insert.table action ID that inserts the table, followed by the three action IDs that set various attribute values to the inserted table.

  5. Go to the Author->Toolbar tab and in the "Current actions" panel, remove the current "insert.table" action and replace it with the insert.table.fixed.attributes action ID.

  6. When editing a DITA topic, pressing the toolbar action for inserting a table should now call your custom action that sets those three attributes on the inserted table.

Wednesday, January 03, 2018

Sorting glossary lists in a DITA Bookmap

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

The idea behind this DITA refactoring action started from this forum post: https://www.oxygenxml.com/forum/viewtopic.php?f=2&t=15284&p=45137#p45137.

Suppose you have a DITA Bookmap that at some point references all of its glossary entries:
            <glossarylist>
                <topicref href="glossary/glossItem1.dita"/>
                <topicref href="glossary/glossItem2.dita"/>
                <topicref href="glossary/glossItem3.dita"/>
                <topicref href="glossary/glossItem4.dita"/>
            </glossarylist>
and you want to have all of these glossary topics sorted alphabetically by title as they appear in the PDF output.

One option for this is to create a PDF customization that automatically sorts the glossary entries no matter what order they were originally specified in the DITA Map.

The other option is to create a custom Oxygen XML Refactoring operation that, when applied on the DITA Bookmap containing the "glossarylist", will sort the glossentries in alphabetical order according to the title of each glossentry.

The following steps will help you achieve this:
  1. Somewhere on disk, create a folder (for example, customRefactor) and add a reference to it in the Oxygen Preferences->"XML / XML Refactoring" page.

  2. In that custom folder, create an XML file (for example, sortGlossentries.xml) that has the following content:

    <refactoringOperationDescriptor 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.oxygenxml.com/ns/xmlRefactoring" id="op_tck_rp1_hcb" name="Sort glossentries">
        <description>Sort glossentries.</description>    
        <script type="XSLT" href="sortGlossentries.xsl"/>
    </refactoringOperationDescriptor>

    This particular descriptor file contains the name of the operation, its description, and points to an XSLT stylesheet that will be applied to sort the entries in the DITA Bookmap.

  3. In the same folder, create a file called sortGlossentries.xsl with the following content:

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        exclude-result-prefixes="xs"
        version="2.0">
        <xsl:template match="node() | @*">
            <xsl:copy>
                <xsl:apply-templates select="node() | @*"/>
            </xsl:copy>
        </xsl:template>
        <xsl:template match="glossarylist">
            <xsl:copy>
                <xsl:apply-templates select="@*"/>
                <xsl:for-each select="*" >
                    <xsl:sort select="document(@href, .)/*/glossterm/text()"/>
                    <xsl:apply-templates select="."/>
                </xsl:for-each>
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>

    This particular XSLT processing copies almost all the Bookmap content unchanged. However, the topicrefs in the glossarylist are sorted according to the glossterm titles specified inside each of them.

  4. Restart Oxygen.

  5. Open the bookmap that contains the glossarylist in the Oxygen main editing area, right-click, choose Refactoring and in the Other operations submenu you will find the new Sort glossentries refactoring action. Invoke the action and use the Preview button to check if the sorting is properly done.