Creating a Platform-Independent System for Redeployable Documentation

DZone 's Guide to

Creating a Platform-Independent System for Redeployable Documentation

Use Eclipse to create a prototypical workflow for managed documentation that is quick, clean, and effective at publishing to multiple formats and locations.

· DevOps Zone ·
Free Resource

Documentation is, often more than figuratively, as far away from development as can be. But often the only person available to write the documentation for a given artifact is the person who wrote that artifact.

The Concept of Structured Documentation for Training and Technical Content

The Darwin Information Typing Architecture (DITA) is an XML data model for authoring and, with the DITA Open Toolkit, publishing.


DITA's core benefit is structured topic authoring: a given topic, for example, installing and integrating the DITA Open Tookit, can be broken down into DITA's native taxonomy of Concept, Task, and Reference. Because DITA specifies the syntax for special kinds of semantic content, it creates a very orderly but extremely flexible system for creating documents.

In practice, DITA offers advantages to both a documentation team and an individual: it can be implemented quickly and cleanly as a tool for single-source publishing to a variety of formats including the CHM format, PDF, HTML5, and Eclipse Help.

DITA's content types and their relationships can be customized ad infinitum (see References), and new documents can be assembled together in different combinations from individual chunks of content. 

If you already have almost any flavor of Eclipse installed and working, the greater part of the foundation is already laid. Eclipse can serve as an environment to create and edit valid DITA, publish locally or deploy to a remote location, and facilitate managed collaboration via Git or Maven that translates the benefits of a development methodology to document production.

In the spirit of DITA, I'll continue the rest of this article according to DITA's native structure, Concept, Task, and Reference. For the most part, Concept was fulfilled by this first section.

Tasks to Create Prototypical Managed Documentation 

In order to get started, you'll need only two external resources:

Installing and Configuring the DITA-OT

The Open Toolkit is the publishing engine that compiles source files into whichever format you choose. 

To install the OT and supporting files:

(This task uses the names and format that the Windows version assumes)

  1. Locate the archive dita-ot-2.1.1.zip

  2. Extract all the files to C:\Program Files (x86)\DITA-OT
    (I used a versionless directory name because it makes handling transitions easier: version 1.3 of the standard is due out later this year.)

  3. Locate the archive containing the DTDs e.g., DITA1.2-dtds.zip

  4. Extract the folder containing the definitions to the root of the DITA-OT installation e.g., \DITA-OT\dtd1.2

Configure Eclipse:

In order to work with DITA in the IDE, Eclipse needs to import the DITA-OT .jar and definition files from your installation.

  1. Navigate to the Preferences window:

    • ANT > Runtime

      • Import the external jars found in \DITA-OT\lib to "Global Entries"

        (DITA-OT uses ANT to create the documentation.)

    • XML > XML CatalogImage title

      1. Add new entry. 

        The dialog presents a few choices, we'll work with those necessary to populate the catalog with the "Concept" definition, but the process is exactly the same for any and all definitions of this format.

      2. Descend to \dtd1.2\technicalContent\dtd
         in your DITA-OT installation and pick the "concept.dtd" file.
      3. Specify the key e.g., Public ID: -//OASIS//DTD DITA 1.2 Concept//EN 
        (This field does not accept totally arbitrary input; here I've used a Public ID key and provided the version of the specification I'm using. You can always use 
        "-//OASIS//DTD DITA Concept//EN" to refer to the latest version of the standard.)
  2. Create supporting files for the ANT build system: (This section of the task assumes you have a project in the works; my examples hold to a generic folder hierarchy that resembles a Maven project, among others.)
    • Create or modify "/local.properties" to contain:
    dita.dir=C:\Program Files (x86)\DITA-OT
    • Create or modify "/Build.xml" to contain:
    <?xml version="1.0" encoding="UTF-8" ?>
    <project name="ProtoMan" default="pdf" basedir=".">
    <property name="dita.dir" location="c:\program files (x86)\dita-ot" />
    <property name="protoman.dir" value="${basedir}${file.separator}src${file.separator}main${file.separator}resources" />
    <target name="pdf" description="Build PDF Output">
    <ant antfile="${dita.dir}/build.xml">
    <property file="local.properties" />
    <property name="args.input" value="${protoman.dir}${file.separator}conman.dita" />
    <property name="args.gen.task.lbl" value="YES" />
    <property name="args.rellinks" value="nofamily" />
    <property name="output.dir" value="${basedir}${file.separator}target${file.separator}pdf" />
    <property name="transtype" value="pdf" />

Create a Prototypical Managed Document

In the previous step, you made Eclipse aware of the definition of a Concept via the XML catalog. This allows you to create a document with syntax highlighting, validation, and contextually-sensitive suggestions. For example, DITA will only permit certain types of elements to hold particular contents, and Eclipse will narrow down its list of suggested elements as you create the document. 

In my example script, I specify the file {protoman.dir}${file.separator}conman.dita:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="ConMan">
<title>ProtoMan // Concept </title>
DITA's core archetypes of information are task, reference,
and concept; together, they create a system wherein markup structure
and contents' relationships coincide.
<p>In contrast to less ordered mark-up, the Darwin Typing
Architecture attempts to impart cohesion on the authoring and
publication process. For the former, DITA provides structured
authoring in a standard ontology. Within DITA, different content
types inherit different characteristics and patterned relationships.
These predetermined positions in a hierarchy enable single source
publishing to many formats including Eclipse Help, CHM, PDF, and

Building it to .pdf output (declared as a target in "Build.xml") obtains the following /target/conman.pdf:

Image title


Because DITA's chunks are contained in individual source files (like "conman.dita"), they can be represented and acted upon separately in a Git workflow, and more profound management precedes from that integration point onward. 

For example, an editor might "check out" a chapter to bring in line with recent changes, and if properly managed, all the documents contingent upon that chapter or that re-use its contents, will automatically be updated when you next decide to build. 

The Maven lifecycles that correspond to processing resources are a possible point of integration, too, via AntRun's ability to call the Ant build script.


  • The DITA for Publishers Group has created multiple sets of further specializations of the concept/task/reference taxonomy and output plugins. 

  • Eliot Kimber's excellent authoring tutorials provide many examples of creating your own types of content, as well as information on using OxygenXML in a way similar to how Eclipse is used here.

  • The free Eclipse plugin Green Elk Tools provides tools for validating the resources and relationships in large DITA documents.

ant, dita, documentation, documentation generator, eclipse, git, html5, maven, pdf, xml

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}