Skip to content

Home

Jump to bottom
Eliot Kimber edited this page Aug 28, 2014 · 3 revisions

Using DITA to create and product sophisticated documentation and other types of human-readable documents is often seen as requiring a large up-front investment in a component content management system (CCMS). This is simply not true. While a commercial CCMS can offer significant value, especially as the size of your content set and your development team grows, you can do a lot with a very small initial investment.

In short, any team of writers using DITA, no matter how small, should be able to productively manage their DITA content using off-the-shelf open-source and low-cost tools. You can get started quickly with DITA without having to worry immediately about your needs for a CCMS. Many groups of writers will never have the content volume or budget needed to justify the investment in a commercial CCMS. That should never be a barrier to using DITA to its fullest.

Toward that end the DITA for Small Teams (DFST) project has been created to help you get your DITA authoring and management system set up and running as quickly as possible.

See the Implementation Status wiki page for the current implementation status.

Project Goals

DITA for Small Teams project has two main goals:

  1. Simply make it generally known that managing DITA content using common tools is possible. In many cases, simply knowing that it can be done is sufficient to allow you to do it—the doing of it is not that difficult, certainly not for the common case.

  2. Providing instructions and supporting tooling as needed for setting up specific sets of tools to make it easier to get something going, even if it's only as a proof of concept. Using these instructions you should be able to get something going in just a few hours, a day or two at most, but really, just a few hours, because it's just not that hard.

Project Documentation

The formal project documentation is served at http://dita-community.github.io/dita-for-small-teams/

What Are the Tools?

DFST focuses on combining the following tool types to create a complete DITA authoring, management, and production system:

  • A Version control system, such as git, Mercurial, and Subversion, for managing your DITA content by authors.
  • A continuous integration system, such as Jenkins, for automating production, publication validation, etc. using existing DITA processors such as the DITA Open Toolkit and ditac.
  • An XML-aware database, such as eXist-db or MarkLogic, to provide DITA-aware search and link management features
  • A DITA-aware authoring tool, such as oXygenXML, XMetal, or Arbortext Editor, for doing the writing

Except for the authoring tools, which are all commercial, there are robust open-source options for all these system components. There are free and low-cost cloud solutions for version control hosting and continuous integration. XML databases like eXist-db and MarkLogic are easy to install and use.

For the XML-aware database, this project provides DITA-specific XQuery modules that implement basic DITA-wareness, which the base XML-aware databases would not normally provide out of the box. The project also provides "commit hooks" for use with git and other version control systems to keep the XML database for searching in sync with the DITA source managed in the version control repository.

See the project documentation for details and project source code for the supporting tooling.

Can You Net It Out For Me?

  1. Set up a remote git repository for your DITA source and clone it to your development machine. This will be the repository for collaborative, distributed management of the DITA source (and any other dependencies: images, media objects, code samples, etc.). It will also manage your DITA Open Toolkit.
  2. Setup or provision from the cloud a Jenkins server and set up Jenkins jobs that react to commits to the git repository to trigger builds or batch validation jobs.
  3. Install eXist-db, configure the DFST XQuery modules, and deploy the DFST-provided git commit hooks to automate loading of your DITA content into the eXist-db database
  4. If you don't already have it, purchase and install the oXygenXML editor
  5. Get to work.

Of course, there are some details there, but that's the basic shape. And of course, none of the specific tools mentioned here are the option option: you could use Mercurial or Subversion or any other version control system that gives you equivalent functions (and any modern version control system will). You could use a different continuous integration system than Jenkins. You could use any other XQuery database as long as it's sufficiently complete: MarkLogic Server (of course), BaseX, Qizx, etc., and of course, XMetal and Arbortext Editor are options if you are working on Windows.

Clone this wiki locally