March 22, 2024: Due to the release of our plugin for DITA-OT, this page will be revised. You can find the latest information on this plugin at www.iirds.org/tools/dita-plugin.

Exchanging DITA Content Using iiRDS

In the following, we provide a brief overview on the exchange of DITA content using iiRDS. The iiRDS Consortium is working to increase compatibility with DITA, with more information to follow during 2023.

DITA is an XML-based information model for technical documentation. It standardizes a topic-based information architecture, which can be customized and extended as needed. There is broad tool support for DITA, including editors and CCMSs.  

DITA has a wide range of applications. Originally, DITA was designed for software documentation, but it is also suitable for any other type of documentation. Because DITA content is already standardized, highly structured, and offers mechanisms for assigning metadata to content, it is a good source format for exchanging documentation based on iiRDS. In the combination of DITA and iiRDS, DITA represents the authoring and content layer, and iiRDS represents the delivery and metadata layer. Both standards thus complement each other.

To map metadata from DITA content to iiRDS, it is important to understand how metadata is handled: DITA offers no clear separation of content and metadata. Metadata is available in the following forms:

• Metadata attributes can be assigned to complete documents or chapters, topics, or fragments within a topic. These attributes can be used to filter content in the published output.
• Metadata elements can be assigned at document level or topic level. These elements allow the definition of complex metadata, that is, metadata where multiple pieces of elements need to be combined, for example, to form a pair between role and skill level or to encode a complete address. Metadata elements cannot be used to filter content by default, but a CDP can filter iiRDS-annotated DITA content.    
• Metadata can be derived from the semantic XML data structures themselves. Examples: The topic type can be derived from the name of the root element. Warning information is enclosed in a hazard statement.  

DITA does not define which type of metadata to choose for a specific use case. In some cases, the same metadata information is available as attribute and as an element, for example, @author and <author>.   

In iiRDS, metadata is clearly separated from content creation. Therefore, a clear strategy is required as to how to derive the iiRDS metadata from the DITA content. The following steps are important:

1. Map DITA metadata to its iiRDS counterparts:

     a. Which iiRDS metadata can be derived from the content itself, for example, element names?

     b. Which DITA attributes or elements can be directly mapped to iiRDS metadata? For example, the @product attribute can be used for product variant in iiRDS.  

2. Extend the DITA document definitions to add new DITA elements and attributes for missing iiRDS metadata:

     a. Prefer attributes if metadata is to be used for filtering, for example, to generate PDFs for individual product variants.

     b. Prefer elements for complex metadata that is not used for filtering, for example, the address of a manufacturer.

3. Create a transformation scenario to transform DITA content into an iiRDS package. This transformation must fulfill two functions:

     a. Generate a rendition, such as HTML or PDF, for the content.

     b. Generate iiRDS metadata from DITA XML elements, attributes, and semantic XML structures.  

Because DITA already provides default transformations for HTML5 and PDF, it makes sense to use them as a basis for the content itself and add the required code to generate the RDF files.