Monday, June 27, 2016

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:

Migrating to DITA

There are multiple reasons why you would want to migrate from unstructured content to structured:

This older blog post details some possibilities of migrating Word documents to DITA: You also have ways to migrate from XML-based standards (like DocBook or XHTML to DITA) using a set of predefined transformation scenarios.

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:

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:

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.

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:

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:

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:

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: Furthermore, here is a way to distribute new DITA file templates to your team:

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:

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: 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: For example, the Oxygen User's Manual is written in DITA and we use a GitHub private repository to collaborate on it:

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):

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.


  1. Regarding collaboration, does oXygen XML Web Author have an integration with the SDL CCMS? It would be helpful to know.

  2. Some time ago SDL developed a plugin for Oxygen XML standalone version. For Oxygen Web Author version we plan to develop a CMIS connector that will also offer support for SDL CCMS. If you want to be notified when it will be available you can write an email to our support address: