DITA: It should just work

If you haven't heard of the DITA standard (Darwin Information Typing Architecture) you should have. DITA is emerging as one of the most important XML-based standards for documentation and publishing to come along in a long time. In a nutshell, DITA provides a solid, extensible, flexible architecture for creating, managing, and publishing documents (in the "information for consumption by human readers" sense) where the document content is managed as sets of small modules ("topics") that can be quickly and easily recombined into different delivery packages using a simple hyperlinking mechanism ("maps").

The basic idea with DITA is that you author your content as individual topics, where each topic is a (more or less) standalone chunk of information that can then be combined with other topics to produce a complete work. Obvious examples are encyclopedias, online help, and so on, publications where the information naturally organizes into individual modules. However, DITA can be applied to a much wider variety of content types, although it may not be appropriate for all types of content.

A key feature of DITA is the specialization mechanism. The DITA standard as published defines a set of core document types that are useful but very generic. However, DITA's specialization feature lets you define new document types that are formally derived from the base types such that any DITA-aware processor can process documents using the new document types as though they used the base types.

In addition, DITA defines a simple syntactic mechanism (the DITAArchVersion attribute) that allows a processor to reliably determine that a given document is in fact a DITA-based document, regardless of what DOCTYPE or schema it uses. That is, DITA documents are self describing as DITA.

These two aspects of DITA, specialization and self description, are very important because they mean that, regardless of the markup details of any DITA document, a DITA-aware processor can always correctly and reliably apply its base DITA processing to those documents.

For RSuite, this means that when RSuite is presented with any DITA document or document type that it's never seen before, it should just work: it should be able to load the DTD or schema and configure it automatically and then load the DITA-based documents and apply to them whatever DITA-specific features RSuite provides, such as treating DITA maps as content assemblies, providing DITA-specific searches, and enabling publication and processing of DITA content using DITA-aware tools such as the open-source DITA Open Toolkit.

That is, for DITA, RSuite should just work.

As an integrator myself that's what I want: Not only should I not have to go to any extra effort to get DITA-based stuff into RSuite, I should be able to expend less effort because I've used DITA.

As a user I should be able to just bring DITA-based stuff into RSuite and have it work with a minimum of effort.

As an engineer building functionality for RSuite I want to provide the smoothest, easiest, most productive user experience I can and DITA allows me to do it.

This ability of DITA to enable this level of convenience and automation has led me to champion this manifesto:

When it comes to DITA, it should just work.

This is my manifesto as a user and integrator of DITA-aware tools: I expect them all to just work, taking advantage of DITA's self descriptive nature to automatically apply specialization-aware processing to DITA content and document types, whatever that means for a specific tool (e.g., automatically using default DITA style sheets and editor customizations in an editor).

This is my manifesto as a provider of DITA-aware tools to you: it should just work. If, as a tool provider, I claim DITA support and it doesn't just work, then I have failed as an engineer.

RSuite's official product plan includes significant support for DITA in the near future. I have started developing a technology demonstration that shows how that support can and should work. If you are interested in having DITA support in RSuite we would be happy to demonstrate what we have working today and talk about what we see as key features and what you see as key requirements for DITA support.

What I have working today is:

• The ability to take any valid DITA document type, specialized in any way (as long as it conforms to the DITA 1.1 architecture specification), and load it into RSuite as a one-step process such that the DTD is automatically configured for use within RSuite (in particular, all the appropriate default managed objects are defined and configured based on their base DITA types).
• The ability to take any valid DITA map and all of the topics it links to, specialized in any way, and import them into RSuite as a one-step process, resulting in a new RSuite Content Assembly that reflects the original DITA map completely (including markup details such as the specific element types used on the map and topicref elements).
• The ability to export any Content Assembly as a DITA map that can then be processed by any normal DITA processor (e.g., the DITA Open Toolkit). If the Content Assembly was created by importing a DITA map, the original markup details will be reflected on export (e.g., if you imported a DITA bookmap map you'll get back a bookmap map on export).
• The ability, using RSuite's generic content assembly manipulation features, to modify an existing map or create a new map.

Even in its current crude, demonstration-purposes-only state, this is pretty significant functionality, functionality that a lot of existing DITA-supporting CMS systems cannot or do not provide.

Obviously we at Really Strategies have a lot of work to do to translate this technology demonstration into production-ready software but there's no particular technical barrier to doing so, it's just workaday engineering to account for all the details. A lot of the work is user interface work--the underlying functionality of RSuite largely does what we need for DITA or can be quickly extended (for example, by providing some additional XQuery DITA-support convenience functions). A lot of the work will be integrating existing and enabling potential back-end processors with RSuite's generic Workflow system so you'll be able to quickly and easily build workflows that send your DITA-based publications out through different DITA-aware processors, including the DITA Open Toolkit, MarkLogic as a DITA-aware dynamic delivery system, and so on.

This project is personally exciting for me: I've been working with DITA for a long time and have built up a largely unrequited set of desires for the functionality a DITA-aware system should provide. Now that I have the opportunity to finally requite these desires my head is literally buzzing with ideas for features and functions that RSuite could provide to make working with DITA-based content as smooth, easy and productive as it can possibly be.

In short, my personal goal is to make RSuite be the DITA supporting system that I've always wanted to have. And you can be sure that if it satisfies me it will almost certainly satisfy you. And if it doesn't, I want you to call me on the phone and tell me how it doesn't so I can get things fixed ASAP.

Stay tuned....