Friday, April 15, 2016

DITA Open Toolkit Frequently Asked Questions (FAQ)

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Below, I tried to put together a set of frequently asked questions and useful links about the DITA Open Toolkit.

What is the DITA Open Toolkit?

The DITA Open Toolkit is a publishing tool used to convert DITA content into various output formats. Its official web site that contains download links and documentation can be found here: http://www.dita-ot.org/.

How do I use the DITA Open Toolkit?

You can download, install and build output from DITA content using the command line.
Also, there are applications that come bundled with the DITA Open Toolkit. For example, Oxygen XML Editor comes bundled with both DITA Open Toolkit 1.8 and 2.x. Oxygen provides a visual means to run the bundled DITA Open Toolkit using a concept called transformation scenarios.

What version of DITA Open Toolkit should I use?

Most of the DITA implementations available are probably still using DITA Open Toolkit 1.8.5. This is  because companies usually have output customizations that have not yet been modified to work with the latest DITA Open Toolkit releases.
However, if you do not have legacy plugins or customizations, you should try to use (whenever possible) the most recent stable version of the DITA Open Toolkit available on the official download page.

What outputs can I obtain using the DITA Open Toolkit?

The entire set of available default output formats is available here: http://www.dita-ot.org/dev/user-guide/AvailableTransforms.html. However, the DITA Open Toolkit can be enhanced by installing plugins to provide additional output formats.

What is the general architecture of the DITA Open Toolkit?

The DITA Open Toolkit is a large mixture of ANT build scripts, Java libraries and XSLT scripts. It has a pipeline-based architecture that uses plugins to publish DITA content to various output formats. Most of the DITA Open Toolkit customizations that you want to make for adding new publishing capabilities or to customize existing publishing choices can be made without modifying its internal core.

What is a DITA Open Toolkit plugin?

A DITA Open Toolkit plugin can provide a new publishing format, customize an existing publishing stage or provide a DITA specialization vocabulary. The plugin can use one of the numerous extension points available in the DITA Open Toolkit: http://www.dita-ot.org/dev/dev_ref/plugin-extension-points.html.
Once you have created a plugin, you can install it in the DITA Open Toolkit either by manual installation or using the new automated installation procedure.

How do I customize the HTML-based outputs?

There are various parameters that can be set to customize the HTML-based outputs: http://www.dita-ot.org/dev/parameters/parameters-base-html.html. For example, you can specify your own CSS stylesheet to be used with the generated HTML output.
You can also create a plugin to customize the HTML outputs by adding a custom XSLT stylesheet: http://blog.oxygenxml.com/2013/12/creating-simple-dita-open-toolkit.html.

How do I customize the PDF output?

The PDF output is obtained by passing the original DITA content to XSL-FO and then generating PDF using an XSL-FO processor. The default XSL-FO processor that Oxygen comes bundled with is the Apache FOP. You can also install and use commercial PDF processors such as Antenna House or RenderX XEP.
You can customize the PDF output either by using a PDF customization folder or creating a PDF customization plugin.
There are a number of other solutions for obtaining PDF from DITA: http://blog.oxygenxml.com/2015/11/possibilities-to-obtain-pdf-from-dita.html.

Tuesday, April 05, 2016

DITA Usage Survey

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

A week or two ago I opened a survey about various ways in which people are using DITA. The survey was taken by more than 50 distinct DITA users and I think it indicated quite clearly some trends in the industry. As I said from the beginning, I'm releasing the entire set of results, including individual responses to questions: https://www.surveymonkey.com/results/SM-3WSR598S/.

I will try below to sum up some of the results:

GIT is on a roll

GIT overcomes Subversion to be the most popular open source solution for version control used in DITA projects. Although most users who responded seem to use open source solutions for version control, there is a solid portion of them using commercial CMSs probably specialized in DITA content. I suspect that people with small to medium projects prefer open source solutions because they are more affordable for their small group of writers.

PDF is still the most popular output format

Most of the participants identified PDF as being their primary output format. Most of them output both to PDF and XHTML but the choice of PDF as the primary output format looks very clear.

Indirect addressing is becoming the main way of reusing content

Plain content references are still used more than content key references but key references are strongly used as well so it seems that indirect ways of addressing content win this game.

DITA 1.3 features

Besides the use of key scopes and branch filtering (which comes as no surprise) it would see that the troubleshooting topic and use of SVG embedded directly inside DITA content come as strong needs that DITA 1.3 fulfills.

Popular image formats

The fact that PNG is the most popular image format comes as no surprise. But SVG coming in as a close second identifies an increasing trend of using vectorial images in technical documentation. Besides the benefit of being vectorial and not losing information when scaled, SVG allows you the unique capability of translating various parts of the image.

Major DITA frustrations

It would seem there are two major DITA frustrations:
  • PDF Customization difficulties. This in my opinion wins the cake in this category. Customizations for the standard PDF output are hard, they required knowledge of XSLT, XSL-FO and of the PDF plugin architecture. But alternatives do exist:http://blog.oxygenxml.com/2015/11/possibilities-to-obtain-pdf-from-dita.html
  • "DITA is perceived as too complex for casual users." This quote says it all, the entry level is high. There are also complains about linking, filtering and reuse. All these come from the DITA flexibility and the fact that each new version adds new elements and ways of working with content. And although DITA can be specialized and reduced as a vocabulary, I suspect not many people are doing that.

That's all I wanted to cover in this post, so go ahead, enjoy the survey results and any comments are as usual welcomed.