DITA meets iiRDS – a new plugin for DITA-OT

This article was first published in tcworld magazine for international information management (April 2024).

The iiRDS Consortium has developed a plugin to support DITA content. The iiRDS package is easy to use and can be customized to meet your project’s needs.

DITA is a well-established authoring standard. It is well structured, customizable, and well supported by an open-source toolkit, the DITA Open Toolkit DITA-OT. You can use DITA-OT to create HTML, PDF, and many other output formats from your DITA files. Single-source publishing is one of the core ideas of DITA and DITA-OT.

The separation of information into topic types and XML as the foundation makes DITA well suited for today’s technical communication needs. With microcontent as the new gold standard, DITA allows the authoring of granular information that feeds content delivery portals, chatbots, and AI-based scenarios such as retrieval-augmented content generation.

Introducing iiRDS

For microcontent to be useful, however, it requires metadata. And here’s where the intelligent information request and delivery standard (iiRDS) comes in. DITA and iiRDS both focus on topic orientation and allow users to get exactly the information they need. For that, iiRDS provides an exchange format that is commonly used to publish technical documentation from content management environments to content delivery scenarios.

iiRDS defines a packaging format and an extensible metadata schema. The packaging format is a ZIP container holding the content files and metadata. Metadata is not part of the content but rather provided in a separate file conforming to the W3C standard "RDF". The Resource Description Framework (RDF) allows you to make Subject-Predicate-Object statements about anything, for example, “Topic A - is about - product B”. And that is the metadata we need for our microcontent.

iiRDS has been around since 2016 and is supported today by many content delivery portals. However, DITA-OT has so far only been supported by plugins that were meant as proof of concept. The plugins required specialized XML elements, were difficult to integrate into existing projects, and lacked documentation. In 2023, the iiRDS Consortium commissioned the development of a new plugin. Developed by Empolis and tested and documented by parson, the new plugin is now available. It builds an iiRDS package, is easy to use, and can be customized to meet your project’s needs.

iiRDS DITA-OT plugin

The iiRDS plugin follows the principles of DITA-OT. After installation, it provides a new transformation type, iirds. With this transformation type you get an iiRDS package that contains HTML files for each of your DITA topic files. The package also contains a metadata.rdf file. This file provides metadata for all the HTML files in the iiRDS package.

The metadata is derived from the XML elements and attributes in the DITA files. For example, the iiRDS metadata Component is derived from the XML element component while the iiRDS metadata ProductVariant is derived from the combination of the prodname element and the product attribute.

Even when there is no explicit metadata in the DITA file, the plugin generates useful iiRDS packages with documents, topics, topic types, and a navigation structure. However, as the main objective of the new plugin was to make it easier to use, not all iiRDS metadata is supported out of the box. What may seem like a shortcoming is, in fact, one of the biggest improvements of the new plugin: You can take your DITA content, even specialized DITA XML, and generate iiRDS packages. The only challenge left is to convince vendors to provide you with a content delivery portal to import your iiRDS packages.

Customization

While the new iiRDS DITA-OT plugin will get you up and running fast, you may end up wanting more. And the new plugin delivers. Basically, every aspect of iiRDS package generation can be customized, including:

• HTML look and feel
• Metadata extraction
• Metadata identifiers
• Processing steps

The iiRDS package contains the basic HTML files generated by DITA-OT, but the iiRDS plugin supports all DITA-OT transformation parameters to customize HTML. You can use your own CSS and XSLT. This will add your custom HTML to the iiRDS package.

But, as we learned, iiRDS is all about metadata. Limited to certain metadata by design, you may want to customize the Java-based metadata extraction. You can do this by registering your custom metadata extractors and supporting all your metadata elements and attributes. Don’t want to use the component element, but want to use your own grouped attribute values in your specialized attribute? Implement the Java service provider interface of the IirdsMetadataHandler and you’re ready to go!

Identifiers are a more technical aspect. To assign metadata to content, both need to be addressed in a consistent and stable manner. Make sure that the same information is always identified by the same identifier. The same goes for metadata concepts. If the identifier for the component gasket changes over time, a content delivery portal will not know that the two components are the same. But just like the metadata extractors, you can implement your own Java service provider and customize the default way of assigning identifiers.

Finally, the iiRDS plugin allows you to add your own processing steps. DITA-OT extension points allow you to add your own ANT processing.

All in all, the plugin is ready for production use. The code base is tested, the functionality is documented and, if there are project-specific needs, you can customize it with parameters or your own additional plugins.

Where to get it

You can find the iiRDS plugin in the DITA-OT plugin registry. It allows for easy installation. Open a terminal in the bin folder of your DITA-OT installation and type the following: dita install org.iirds.dita.package

If you don’t want to install it right away, you can download the plugin from https://iirds.org.

The plugin is published under the Apache 2.0 license and is open for use and customization by the DITA community.