Edit online

DITA XML Editing, Collaboration and Publishing Overview

Radu Coravu
29 May 2024
Read time: 16 minute(s)

Oxygen XML provides a wide range of features for editing, reusing, profiling, reviewing, and publishing DITA XML content. We strive to offer a complete editing, collaboration package which is still flexible enough to be customized for a variety of use cases.

Overview

You can find an overview of the application's DITA XML editing support here: Oxygen XML Editor DITA Editing solution strong points.

Here are some of the key features:

  • Permanent user-based licensing.
  • Available on multiple platforms.
  • Comprehensive support for editing, reviewing, and publishing DITA XML content.
  • Excellent technical support.

For answers to common questions about the overall solution, which companies can benefit from using it, and how it is typically purchased, please see: Oxygen XML As a Technical Documentation Solution FAQ.

General Advantages of Structured DITA XML Editing With Oxygen

  • You own your content, the storage is on your own servers, privacy is insured.
  • You are using a standard (DITA XML) for which lots of tools and publishing choices exist.
  • Reuse content and easily update the reused content in multiple places.
  • Reduce translation costs by reusing content.
  • Lost of publishing format choices (WebHelp, PDF, Windows Help, Word, Markdown, etc).
  • Enforce consistency through structured validation (custom Schematron rules, Quick Fixes).

DITA Maps Manager

The DITA Maps Manager view allows editing, validating, making project-wide changes and publishing.
  • Create new topics and references to them either individually or in bulk by using the Fast Create Topics action.
  • Project- wide Operations:
    • Validate and Check for Completeness.
    • Search references.
    • Rename, move, or delete existing topic references.
    • Map-wide XML refactoring actions.
    • Find/Replace in Files.
    • Spell Check in Files.
    • Open/Find Resources.

If you want to learn more about editing DITA XML with Oxygen, you can watch recordings of past webinars here: Resources for learning DITA with Oxygen.

Topic Editing

Oxygen XML Editor provides comprehensive support for editing DITA XML Topics. Here are some key features:
  • Ability to change the Tags Visualization Mode.
  • Access to a CSS Styles drop-down menu.
  • Availability of a Content Completion Window.
  • Helpful side views, including the Outline, Attributes, Elements views, and DITA Reusable Components.
  • DITA-specific actions accessible through the Menu, Contextual Menu, and Toolbar, such as:
    • Inserting links.
    • Reusing content.
    • Editing Profiling Attributes.
    • Working with tables.
    • Inserting references to image and media resources.
    • Inserting lists, paragraphs, and applying bold, italic, or underline styling.
  • Various methods to insert links and content references, including copy/paste and drag and drop.

For more information on editing DITA XML with Oxygen, you can watch past webinar recordings: Resources for learning DITA with Oxygen.

Content Reuse

The DITA XML standard offers a wide range of content reuse features. Oxygen allows you to harness the full potential of the DITA 1.3 standard:
  • Reuse product names using key definitions with keywords.
  • Reuse XML elements in multiple places.
  • Reuse ranges of XML elements.
  • Push reusable content into target topics.
  • Reuse entire DITA XML topics in various parts of the DITA map.
  • Use DITA 1.3 key scopes to reuse topics with variable content in different contexts.
Oxygen provides several user interface features to insert reusable content:
  • DITA Maps Manager -> Insert Key Definition with Keyword
  • DITA XML topic editing toolbar with options to Reuse Content.
  • Using special paste to insert content references in topics.
  • The DITA Reusable Components side view.
  • Content Completion actions to insert reusable content (keyrefs and conrefs).

For more information on DITA XML content reuse with Oxygen, check out the past webinar recordings: Resources for learning DITA with Oxygen.

Profiling/Filters

Profiling capabilities make it possible to create many similar user manuals from the same DITA XML content.

With Oxygen, you can:
  • Set values for the DITA profiling attributes. These can be easily managed to filter content in the published output.
  • Change between profile sets. This lets you see how the edited content will look before publishing.

You can watch past webinar recordings that cover DITA XML profiling with Oxygen: Resources for learning DITA with Oxygen.

Project-wide Refactoring

  • The Main Files feature in the Oxygen Project view enables powerful refactoring operations:
    • You can move or rename one or multiple files.
    • You can change directory names or move entire directories.
  • You can apply XML refactoring actions to multiple files or entire folders.

Validation, Structure, and Terminology Checks

  • The Validate and Check For Completeness tool available in the DITA Maps Manager view performs dozens of useful validation checks starting from a DITA map or from a DITA Open Toolkit project:
    • Validate each map and topic according to the standard schemas.
    • Validate each map and topic with a custom Schematron schema.
    • Check for broken links.
    • Check for profiling/filter problems.
    • and so much more....
  • Schematron checks with quick fixes can be added to report structural problems.
  • The built-in spell checker and the Terminology Checker add-on can be used to check for content-related problems.

Migrating from Other Formats

  • You can use the smart paste feature to convert Microsoft Word or web content into DITA XML format when you paste it.
  • Alternatively, you can use the Oxygen Batch Documents Converter add-on to convert various document formats including Word, DocBook, Markdown, HTML to DITA XML.
  • You can also perform on-the-fly conversions for Markdown, OpenAPI, or Microsoft Word documents that are directly referenced in a DITA map.

Integrating Other File Types in Your DITA Map

You can integrate Markdown files directly in your DITA Map, allowing subject matter experts to contribute content.

You can also integrate other file formats like Word, Excel, OpenAPI, HTML directly in the DITA Map.

Framework Customizations

You can customize the overall DITA XML editing functionality in several ways:
  • Add new actions to the DITA-specific menus and toolbars.
  • Remove existing actions that you don't need.
  • Customize the content completion window by adding or removing entries.
  • Customize the visual editing experience by using your own custom CSS.
  • Use your own new file templates to create new documents.
  • Add custom validation stages by using custom schemas or Schematron checks.
  • And there are many other customization options available!

Useful Add-ons

The Oxygen default add-ons repository provides a range of helpful add-ons. Some of the most notable ones include:
  • Git Client add-on - Allows you to connect to Git repositories.
  • Content Fusion Connector - Enables subject matter experts (SMEs) to review technical documentation content directly in a web browser.
  • Batch Documents Converter - Converts documents from various formats such as MS Word, DocBook, Markdown, and XHTML to DITA XML.
  • Terminology Checker - Checks for terminology-related issues in your content.
  • Fluenta DITA Translation Add-on - Uses the Fluenta third-party library to create XLIFF exports from DITA maps and import DITA maps from translated XLIFF files.
  • Oxygen AI Positron Assistant - Provides AI-powered assistance for content creation and editing.
  • Oxygen Feedback Connector - Provides ways to see and change (delete, accept, reject) comments offered in the Oxygen Feedback system to writers working in the desktop application.

Storage

Possibilities to store the DITA XML content:

Review

There are several ways for people to provide feedback on technical documentation:
  • Internally review the content directly in the Oxygen desktop application:
    • Use change tracking to modify existing content or to accept/reject changes.
    • Use the comments feature to add comments, reply to comments, or resolve them.
  • Review content internally using the Content Fusion platform.
  • Review content internally or externally by publishing it to WebHelp Responsive output and using the Feedback platform.
  • Review content internally or externally by publishing it to WebHelp Responsive output or PDF and using edit links.

Content Fusion Collaboration Platform (Web Browser)

  • Installation as a server component in the client's own network.
  • Live demo web site to test and explore: https://fusion.oxygenxml.com.
  • Create and upload review tasks for subject matter experts.
  • Connect to Git projects:
    • Allow creating review tasks.
    • Edit DITA XML content in your personal workspace.
    • Edit other types of documents.
    • Create publications and publish to WebHelp and PDF outputs.
    • Use connectors to push publications to live web sites.

Translate

Oxygen provides support for:
  • Exporting a DITA map as a zip file from the DITA Maps Manager view, which can be sent to a translation agency.
  • Using the Fluenta DITA Translation Add-on, a third-party library, to generate XLiff exports from DITA maps and import DITA maps from translated XLiff files.

For a more detailed explanation of the translation process, please refer to the following article: Translating your DITA Project

Publishing

Oxygen comes with a built-in Oxygen Publishing Engine that is based on the DITA Open Toolkit open-source project. This engine allows you to publish DITA XML content to various outputs such as WebHelp Responsive, PDF (CSS customization based), PDF (XSL-FO customization based), MS Word, EPUB, Windows Help, Markdown, and more.

You can customize the WebHelp Responsive and PDF (CSS customization based) outputs by creating publishing templates in two ways:

Publishing can also be configured to run server side by using the Oxygen Publishing Engine.

For more information about publishing customizations, see the following articles: Publishing Customizations.