Guided DITA Authoring Solution Overview

Learning to Work with DITA and Oxygen

You can find useful links for learning how to edit DITA using Oxygen in this previous blog
post: Resources for learning DITA with Oxygen.

Migrating to DITA

There are multiple reasons why you would want to migrate from unstructured content to
structured: Migrating to a Structured Standards-based Documentation Solution.

This older blog post details some possibilities of migrating Word documents to DITA: How to Migrate from Word 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.

Restricting the Visual Editing Experience

The entire visual editing experience in Oxygen’s Author editing mode is driven by
CSS. 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 contributes a combination of buttons, hints, and
form controls designed to assist and guide the author. The following blog post details how a
custom CSS that will be used to enhance the visual editing experience can be created and
shared with others: Customizing the DITA Visual Editing Experience.

Implementing Your own Style Guide

Suppose you are a team of technical writers collaborating on a DITA-based project and 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: Implementing your own Style Guide.

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: Controlled Attribute Values for your DITA Project.

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 provide authors various ways to rectify the problem. This blog post contains more
details about this: Schematron Checks to help Technical Writing.

The DITA framework can be extended to add new Schematron rules: Sharing Schematron Validation Rules.

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: DITA Map Validate and Check for Completeness Overview.

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 Oxygen SDK (Part 2: Frameworks).

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: Document Type Extension Sharing.

Furthermore, here is a way to distribute new DITA file templates to your team: Sharing New Custom File Templates for a Specific Vocabulary.

Sharing Global Application Settings with Your Team

Suppose 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: Sharing Application Settings.

Collaboration, Content Management, and Version Tracking

All major Content 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 provide the possibility of collaboration on a single DITA
project: Collaboration (Teams working on a common XML project). For
example, the Oxygen User’s Manual is written in DITA and we use a GitHub
private repository to collaborate on it: Collaboration for Documenting a Software Product using DITA.

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.