Aspects and Facets of a Healthy DITA Project

How should a Happy and Healthy Documentation Project Look Like?

Do you have a Healthy Project?

• Focus on writing and not on workflow.

• Involve peer-reviews, SMEs and end users.

• Easy start for first-time contributors.

• Easier produce deliverables and correct errors in older deliverables.

• Allow for future evolution: more writers, more outputs, more content, more products.

Why do big companies use the DITA standard?

• Standard means owning your content and no vendor lock-in (editing or publishing).

• DITA works very well with topic-based authoring.

• Lots of content reuse potential.

• Reuse lowers translation costs.

DITA Doc Project Aspects

• Storage

• Workflow

• Collaboration

  • Sharing Common Constraints (editing, validation, spell check dictionaries, ...)

• Structure

  • Managing links and reusable content

• Translation

• Publishing (Producing Deliverables)

Storage

• Commercial content management systems (CMS).

• Open Source version control systems: Git, Subversion, CVS

Version Control

• Ability to Tag Releases and Create Branches.

• See history for resources.

Working with the storage system

• Commercial CMSs – Remote editing, locking.

• Open Source version control systems – Local working copies, no editing restrictions → conflicts.

  Hint: Maybe you can use the same storage system as software developers in your company.

Collaboration and Workflow

• We invest a lot of time each day collaborating with our team or external collaborators.

• Collaboration should be as comfortable as possible.

Workflow

Issue tracking

• Using workflow features in the CMS

• Using issue management systems like Bugzilla, Atlassian JIRA or Trello.

  • Tip: Linking the product development with the documentation development.

Issue Tracking Examples

Custom workflows

• Documentation task specific workflow

• Integrate QA and documentation in software development process

Issue tracking – Simple Documentation Workflow

Issue tracking – Development and Documentation Workflow

Issue Tracking and Storage Integration

Issue Tracker can provide a single place where you can monitor a ticket from start to end, including:

Issue description and details

• Who worked on that issue

• What was changed in the application

• What was changed in the documentation

• Who should be notified when issue is resolved.

Involving Subject Matter Experts

• SMEs provide original content (DITA or Markdown or ...)

• Let SMEs review the published output.

  • HTML with feedback forms

  • PDF with comments.

  • Formal review with web editing tool integrated with storage system.

  • Informal review DITA content using change tracking and comment capabilities

How can end users collaborate with us?

• Send feedback via email/forum/phone.

• Send feedback in the published HTML output.

• Give feedback using an online DITA editing tool with comment-only capabilities.

Contribution Consistency

Sharing common settings between writers

• Custom style guide.

• Specific editing enhancements.

• Specific validation settings.

• Controlled attribute values.

• Custom spell and auto-correct dictionaries.

• Various other common preferences.

Custom Style Guide

The style guide is internal documentation about how to write documentation.

How can we remember what’s written in the style guide?

• Searchable help output from internal style guide.

• Find an automatic way to impose style guide rules when editing.

Automating Style Guide Rules

https://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html

• Schematron to add custom validation rules.

• Schematron Quick Fixes to propose quick fixes for each custom error message.

Using the same terminology rules

http://blog.oxygenxml.com/2017/06/checking-terminology-when-editing-in.html

• Custom Spell dictionaries.

• Custom auto-correct mappings.

• Advanced terminology checkers like Acrolinx, HyperSTE or LanguageTools.

• Building your own terminology checker using Schematron.

DITA Project Structure

• Organizing various resources in various folders

• Some CMSs may not consider this relevant.

File and folder naming/organization conventions

• By type:

  • Tasks/t_installation.dita

  • Concepts/c_profiler.dita

• By semantics:

  • xslt_debugger/backmapping.dita

  DITA Style Guide

Managing Content Reuse

http://blog.oxygenxml.com/2015/11/dita-reuse-strategies-short-tutorial.html

• Separate folders containing reusable content.

• Keep dictionaries of reusable components

• Prefer indirect references (conkeyrefs)

Managing Links

http://blog.oxygenxml.com/2017/06/dita-linking-strategies.html

• Prefer indirect links (key references)

• Reuse link targets

• Re-direct links depending on publication

• Use relationship tables

Project-wide refactor operations

• Convert between various topic types.

• Rename or move one or more topics.

• Change XML structure in topics from the entire project.

  • Example: Change the value of a specific attribute.

Translation

http://blog.oxygenxml.com/2018/05/translating-your-dita-project.html

• You create your content in the primary language using a DITA authoring tool .

• Send a copy of the relevant DITA files to the localization service provider (LSP).

• Receive translated DITA content back from (LSP).

Optimizing for translation

• Use a controlled vocabulary (simplified English).

• Avoid reusing inline elements other than product names.

  https://lists.oasis-open.org/archives/dita/201301/msg00029.html

• Avoid profiling/filtering content at inline level. https://www.infomanagementcenter.com/publications/best-practices-newsletter/2010-best-practices-newsletter/successful-localization-in-dita/

Publishing

• Map-wide Validation and Consistency Checks

• Validate each topic according to DITA standard.

• Check for broken links, key references and content references, missing images or referenced resources.

• Check for broken links to remote web sites.

• Check for broken links in the context of profiling filters.

Producing the deliverables

• Checking the project before publishing.

• Sharing publishing customizations

• Automatic production of deliverables either via CMS or via an automated open source server (Jenkins).

Useful links

• DITA Style Guide (by dr. Tony Self):

  https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/

• Intelligent Style Guide (by George Bina):

  https://github.com/oxygenxml/dim

• Oxygen XML Blog (Reuse, Linking, custom validation, sharing settings):

  http://blog.oxygenxml.com/

Conclusions

A healthy DITA project needs to:

• Be Manageable.

• Allow for scalability.

• Allow for easy collaboration.

• Allow for detection and correction of mistakes before the deliverables are published.

• Allow for correction of mistakes after the deliverables are published.

But don’t panic if you do not have all the aspects of a project covered, your project does not need to be perfect, it needs to be perfectible.

Oxygen XML Editor - DITA Oriented Tips And Tricks

Oxygen XML Editor has about 18 years of development under its wings. During these years, we added lots of functionality and many of our users usually do not know more than 20-30% of Oxygen's features. So this presentation is intended for technical writers using Oxygen to write DITA content and who may want to find out more about their tool.

Add-ons

There are lots of free add-ons provided by the Oxygen team that can be installed in an Oxygen standalone version. I will enumerate some of the most interesting one:

• Git add-on. This plugin adds a side view allowing you to do some common Git operations like pull, commit, push (mostly 90% of what a regular Git user would do).
• Content Fusion Connector add-on. Collaborate with your peers by sending them links that allow them to give you feedback on your work using a web browser without the need to pre-install anything on their side.
• Translation package builder. Small plugin that can be used to prepare a zip file containing only the topics that have changed from one version to another.
• Batch convertor add-on. Converts multiple HTML, Markdown, Excel files to DITA.

Project-related Functionality:

The Oxygen Project view is the place where you can organize and apply batch changes to all your DITA resources:

• Master files support. Enable master files support in the DITA project, add your top level DITA Maps as master files and any structure changes, renaming or moving files will automatically update all links in the DITA Project. Also works for renaming/moving image resources.
• Store options at project level. Almost all of Oxygen's preferences pages can be saved at project level. Once you do that, you can share the project.xpr file with somebody else and when they open it, they will also get the settings set inside the project.
• Compare files/folders.
• Refer to multiple folders.
• Batch operations: Select a folder in the project and use the "Transform", "Validate", "Format and Indent", "Find/Replace in Files", or "Spell Check in Files". Or use the "XML Refactoring" action to apply a refactoring stylesheet over all the selected files.
• Filter files. You can instruct the Project view to hide various file types.

Navigation:

Actions to find opened files, find files containing a certain content or navigate between files.

• In the main Window menu, you can find the Next/Previous Editor actions and their shortcuts. Together with the Switch editor tab action, these help you navigate between opened XML documents.
• The Open/Find Resource view (main menu Window->Show View) allows you to search for file names, search in file contents, or search for files containing comments or change tracking.
• Right-click the tab of an opened DITA document and use the Copy location action. Or use the Show in Explorer/Finder action to locate the file.
• Use the main menu File->Reopen last closed editor action to re-open the last closed file.
• Open a DITA topic in the Text editing mode, right click, choose Go to definition to open the DTD, XML Schema or RelaxNG Schema at the precise location where that DITA element is defined, something useful for debugging DITA specializations.
• Use the Navigation toolbar to Go back/forward/last modification.

Find/Replace Functionality

The Find/Replace functionality is the bread and butter of any editing application and Oxygen has lots of functionality in this regard:

• Find/Replace in Files.
  • Restrict to XPath - If you want to make replacements only in certain parts of the XML document, the XPath restriction can be used to focus only on certain attributes or element content.
  • Ignore Whitespaces - You should usually check this checkbox as there is always there is a possibility what the words you are searching for may be split on multiple lines in the XML content.
• The Find menu → Find Next/Previous actions allow you to find the next/previous occurrence of the current selected word(s). Or you can use the Find All action to find and highlight all occurrences of a word or a sequence of words.
• The Find menu → Find all Elements action shows a dialog box allowing you to find elements or attributes containing a sequence of words.
• The Find menu → Quick find toolbar is a compact toolbar giving you access to search functionality.
• The XPath allows you to use XPath expressions (i.e. //comment()[contains(., 'TODO')]) to search the current topic or a set of topics for elements, attributes, or comments matching a set of conditions.

DITA Maps Manager

The DITA Maps Manager view's contextual menu gives you quite an impressive array of useful actions:

• Fast create new topics. Create a set of DITA topics by specifying only their titles.
• Add references to multiple topics.
• Create key definition with keyword.
• Edit Properties - You can even set profiling attributes on multiple selected topic references.
• Export DITA Map - Export your DITA Map to a zip archive ready for translation.
• Find Unreferenced Resources - Find all resources which are no longer used in a DITA project.
• Refactoring menu
  • Rename/Move topic - Renames a topic and all references to it.
  • Rename key - Rename a DITA key and all its references in the entire project.
  • Conversions between topics - Convert between topics, tasks, concepts, and references for multiple selected DITA files.
  • Convert nested sections to new topics - Convert all sections located inside a topic to new topics.
  • Convert nested topics to new topic - Convert all nested topics to new topic files.
  • Apply custom refactoring scripts - Create and apply your own XSLT or XQuery refactoring scripts.
• Find/Replace in Files.
• Spell Check in Files.
• Search References - Search all references to a particular referenced topic.
• Remove from Disk - Check in how many places a topic is referenced and then remove it from disk.
• Open with resolved topics - Open the DITA Map with all topic references expanded, useful if you want to have an overview of the entire publication.
• Synchronized selection between DITA Maps manager and main editor area - Anytime a DITA topic is opened both in the DITA Maps Manager and the main editing area, moving the selection in one instance will also move the selection to the corresponding place in the other.

Editing in the Author Visual Editing Mode

• Maximize editor area - Double-click the opened editor's tab to hide all side views and maximize editing space, double click again to show the side views.
• Increase/decrease editor font - Use Ctrl/CMD +/- to increase or decrease the font in the current edited document.
• Inserting elements - Pressing ENTER in the Author visual editing mode will show you a list with all possible elements that can be inserted. If you choose an invalid element, Oxygen will find a place for it. You can also add custom actions or code templates to the content completion list.
• Select content then press ENTER to surround the content in a new element.
• Select multiple intervals - Press the Ctrl/CMD button when selecting text to select multiple text intervals. Once you do that, you can use toolbar actions like Bold, Italic, or Underline or you can use the Edit Profiling Attributes action to set profiling attributes on all the selected items.
• In-place attributes editor - Instead of using the Attributes view, you can press Alt-Enter to edit attributes for the current element in a small pop-up dialog box.
• Select an entire element - Triple-click inside an element's contents to select the entire element. After this, you can move the element to a new place.
• Double-click to select by word, then drag the mouse to select the content word by word.
• Move elements (especially paragraphs, list items) up or down (ALT-UP/DOWN), indent or unindent list items (Tab, Shift-Tab).
• Select content and then use the Toggle comment action (contextual menu Refactoring submenu) to quickly add an XML comment around it.
• In the contextual menu the Text submenu contains useful actions to count the number of words in the entire document (or in the selected text), convert the selection to upper, lowercase, or sentence case
• Bookmarks - Click the vertical left side bar in the editing area to add a bookmark. Navigate to that bookmark even after the file has been closed using the Ctrl/CMD + number shortcut.
• Collapse other folds - Click a fold triangle in the Author visual editing mode and you can choose to close all other folds, useful when working with multiple sections in the same file.

• Code templates - Define small fragments of XML content that can be inserted either by defining a shortcut key or by pressing ENTER in the editing area.

• Editor variables - Certain Oxygen-specific macros can be automatically expanded. For example, a code template that inserts the current author name can use this editor variable:

  <author>${author.name}</author>

  or a code template that surrounds the selection inside a <keyword> element:

  <keyword>${selection}</keyword>

  or a code template that first asks the end user for their name and then inserts it in the document:

  <author>${ask('Author Name', generic, 'John Doe')}</author>

  Code templates can also be used when creating new file templates.
• Outline Quick find filter - The Outline view contains a filter that can be used to reduce the number of elements displayed in it (for example, display only the contained topics).

DITA-specific Editing in the Author Visual Editing Mode

• DITA Reusable Components view. You can use this side view to quickly search for and insert references to keys or to reusable components.
• Inserting links to resources. Besides using the toolbar actions you can also:
  • Drop a file from an outside location. Drag a DITA topic or other resource from the Explorer/Finder or from the Oxygen Project and drop it inside an opened DITA topic to insert a reference to it.
  • Paste a URL in the editing area to insert a reference to it.
• Links to images:
  • Drop images from the Project view in the main editing area to insert references to them.
  • Copy an image and then paste it in the editing area to insert a reference to it.
  • Double-click broken image reference to modify attributes.
• Reuse content:
  • Copy an element that has an ID set on it and then right-click elsewhere and use the "Paste Special → Paste as content reference" to insert a content reference to the element.
• Select multiple sibling paragraphs and use the Insert list item toolbar item to convert them all to list items. Select multiple list items and use the Insert table toolbar action to convert them to a table.
• Working with tables:
  • You can right-click inside a table and use the Table Properties action to change lots of table-related settings.
  • You can sort tables based on certain criteria.
  • In the contextual menu Refactoring submenu you can find actions to convert between CALS and simple tables.
  • You can select an entire table by clicking its left corner and select an entire row by clicking to the left of it.
• Add hotspots to images - You can right-click any image reference and use the Image Map Editor to configure target links for various parts of the image.
• You can right-click inside an element and use the About Element contextual menu item to find out more about it.
• Pasting content from web browsers, Excel spreadsheets, or Word documents inside a DITA topic produces the equivalent DITA content.
• The Styles drop-down toolbar menu allows you to choose between various CSS styles to apply while editing. The Hints and Inline actions layers should be interesting for you to experiment with. Or you can add your own.

Preferences:

Oxygen has a lot of global settings that can be configured, I will just list what I consider to be the most important ones:

Menu shortcut keys - You can use this preferences page to assign or to see the shortcut for any action available in Oxygen.

Fonts - This page allows you to change the default fonts used in the application.

Appearance - Change the default color theme in Oxygen (the Graphyte theme is quite popular).

Spell check - Customize the spell checker settings, use custom spell check dictionaries.

Save - Settings to automatically save or to check for errors before saving the file.

External tools - Define various command line tools that you can launch from Oxygen.

Annotations - Disable the tooltips which appear when hovering over various elements (useful if you have a small screen).

Tools

The Tools main menu is worth exploring sometimes. You can invoke XML refactoring actions from it or open other small applications like the SVG viewer.

Import

The File menu offers the possibility to import HTML, CSV, Excel files, or database content as XML.

Other Views and Toolbars:

You can right-click in the toolbar area and use the Configure Toolbars action to see what toolbars are available or what toolbars can be removed.

The Symbols toolbar is quite interesting if you often want to insert symbols that are not on the current keyboard.

Other Small Tips:

The main Window menu has actions to tile all opened XML documents and also to enable synchronous scrolling in them (useful if you want to look at similar XML documents and maybe to copy/paste between them).

Keeping in Touch

Oxygen's Help menu allows you to use the Report problem action to contact us directly. The Support Tools->Randomize XML Content action allows you to randomize the content of an XML project before sending it to us for tests.

And there are a lot of other ways to get in touch with us or to find various videos or tutorials to read: https://www.oxygenxml.com/technical_support.html.

Oxygen XML Editor DITA Editing solution strong points

We are sometimes asked which are the differentiating features between Oxygen XML Editor and its competitors when it comes to DITA Editing. So below I tried to list some differentiating features (strong points) that Oxygen has:

• User based license which allows somebody to install Oxygen on multiple computers (work computer, home computer) as long as they are the only ones using it: https://www.oxygenxml.com/eula.html.
• Transparent pricing, prices are available on the web site: https://www.oxygenxml.com/buy.html.
• Great technical support. You can ask us questions via email or via the forum.
• Cross platform availability. Being able to run Oxygen on Windows, Mac or Linux.
• Complete DITA Editing support:
  • Lots of pre-defined actions to insert reusable content, images, links, videos.
  • DITA-specific helper views (DITA Maps Manager, DITA Reusable Components)
  • Support to customize the editing environment: add custom actions, remove current actions, customize content completion items, create custom validation or transformation scenarios.
  • Powerful publishing solution for producing responsive WebHelp and PDF using CSS to style the output.
  • Publishing to output formats like Windows Help (CHM), Ms Word, EPUB, Eclipse Help included.
  • Lots of commercial DITA CMSs have integrations with Oxygen.
• Support for change tracking and for adding comments in the editor along with a special Review view to review changes: https://www.oxygenxml.com/doc/versions/21.0/ug-editor/topics/author-managing-changes.html
• Support to add third party plugins and enhance Oxygen's functionality. And lots of free add-ons already available to add support for Git integration, DITA translations and Batch conversions from various formats to DITA.
• Support to add custom validation rules based on your internal style guide. The rules can be implemented using the Schematron standard and you can also add quick fixes for them: http://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html.
• Support to send DITA content to reviewers using the Content Fusion add-on.

Adding support for embedding Latex equations in DITA content

LaTeX is a high-quality typesetting system that includes features designed for the production of technical and scientific documentation. LaTeX can also be used to express mathematical formulas in a textual format. By default, web browsers and PDF readers do not have support to show mathematical equations written in LaTeX but there are open source projects that can read LaTeX and convert it to other image types.

Adding support for writing LaTeX equations in DITA topics would imply three stages:

• Find a way to write the equation in the DITA XML content. You can either create a DITA DTD specialization and add a new element (for example, called <latex> and it extends the DITA <foreign> element). Alternatively, you can use the DITA <foreign> element with a specific @outputclass attribute value directly:

  <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
  <topic id="testEquation">
      <title>Test equation</title>
      <body>
          <p><foreign outputclass="embed-latex">L' = {L}{\sqrt{1-\frac{v^2}{c^2}}}</foreign></p>
      </body>
  </topic>

• If you want Oxygen to properly present the LaTeX equation when editing in the Author visual mode, you need an Oxygen plugin that converts the equation content to an image. There is a sample plugin that does that here: https://github.com/oxygenxml/wsaccess-javascript-sample-plugins/tree/master/latex-images-support. You can download and copy the plugin folder latex-images-support to the Oxygen plugins folder, then restart Oxygen.
• Publishing to HTML-based and PDF outputs. This DITA Open Toolkit plugin automatically converts LaTeX images to SVG when publishing: https://github.com/oxygenxml/dita-latex.

Migrating Various Document Formats to DITA

Most companies do not start new DITA-based projects from scratch. They already have content written in various other formats and somehow they need that content converted to DITA. In this blog post, I will offer some conversion advice depending on the format of your current project.

Migrating DocBook content to DITA.

Because DocBook content is XML, migrating it to DITA is quite straight forward:

1. You first convert the DocBook document to a single large DITA composite file and you can do that with the predefined transformation scenario bundled with Oxygen called DocBook to DITA.
2. There is a utility XSLT stylesheet on the Oxygen XML GitHub account that can convert a DITA composite to a DITA map with separate DITA topic files: https://github.com/oxygenxml/old-userguide-docbookbased/blob/master/split-DITA-topic.xsl

Migrating Microsoft Word content to DITA

The Oxygen XML User Manual has a detailed topic enumerating the possibilities to convert Microsoft Word content to DITA: https://www.oxygenxml.com/doc/versions/20.1/ug-editor/topics/ooxml-to-dita.html?hl=migrate%2Cdita

Migrating Excel content to DITA

You can use Oxygen's Smart Paste functionality to copy content from an Excel spreadsheet and paste it inside an opened DITA topic. Also, as an alternate possibility, the Oxygen Resources Converter add-on was updated to be able to batch convert Excel to DITA: https://github.com/oxygenxml/oxygen-resources-converter

Migrating LibreOffice content to DITA

LibreOffice documents can be saved in Word format, and once you do that, you can convert the Word content to DITA as described above. Alternatively, you can save the LibreOffice documents to DocBook and then apply the DocBook to DITA conversion technique described above.

Migrating Google Docs to DITA

You have three possibilities to convert Google Docs to DITA using Oxygen:

• Copy/Pasting from Google Docs to a DITA Topic opened in Oxygen in the Author visual editing mode should work and convert the pasted content to DITA.
• Save the Google document as OpenDocumentFormat (ODF) then save the ODF document as DocBook with Libre Office, then apply the DocBook to DITA transformation scenario shipped in Oxygen to convert DocBook to DITA.
• Save the Google document as HTML then use the Oxygen batch converter add-on to convert it to DITA: https://github.com/oxygenxml/oxygen-resources-converter

Migrating Markdown content to DITA

The DITA Open Toolkit publishing engine bundled with Oxygen allows you to reference Markdown files directly in a DITA map and either publish them directly or export the Markdown files to DITA one by one: https://www.oxygenxml.com/doc/versions/20.1/ug-editor/topics/markdown-dita-x-dita2.html. If you want to convert multiple Markdown documents at once, you can use the Oxygen Resources Converter add-on: https://github.com/oxygenxml/oxygen-resources-converter

Migrating HTML content to DITA

Using Oxygen's Smart Paste functionality, you can open the HTML documents in a web browser, then copy the contents and paste it in a DITA topic opened in Oxygen's Author visual editing mode. If you want to convert multiple HTML files, you can use the Oxygen Resources Converter add-on: https://github.com/oxygenxml/oxygen-resources-converter

Migrating unstructured FrameMaker to DITA

There is a FrameMaker plugin that can be used for this type of conversion: http://leximation.com/tools/info/fm2dita.php

Migrating MadCap content to DITA

Some recent MadCap versions seem to have facilities to export content directly to DITA. Otherwise, you will need to convert XHTML content to DITA with a custom XSLT stylesheet to preserve variable references.

Migrating other formats to DITA

You may find third-party applications (like Pandoc) that can convert your content to HTML or to some kind of XML format like DocBook. Once you have HTML or DocBook content, you can convert them to DITA using the advice above.

Translating your DITA Project

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.

Guided DITA Authoring Solution Overview

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

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.