What is DITA?
January 19, 2017
The OASIS Open Darwin Information Typing Architecture (DITA) is a standard XML-based architecture for representing documents intended primarily for consumption by humans. It provides architectural features for content modularity, content reuse, and controlled extension of document vocabularies in a way that ensures interoperability of DITA documents.
DITA is an OASIS Open standard first published in 2005 and last updated in 2015 with the publication of version 1.3. The DITA architecture was originally developed inside IBM for IBM technical publications, especially Web-based content, and donated to OASIS Open in 2004.
That's the formal definition but what does that really mean?
- Enable interchange and interoperation of XML content from a wide variety of sources without requiring everyone involved to agree on a single overarching document type definition.
- Enable reuse of content among different publications and within the same publication.
Requirement (1), interoperation, is satisfied by DITA's specialization facility, which allows for controlled extension of document vocabularies while guaranteeing the interoperability of the documents in the context of general-purpose DITA processors. Conforming DITA documents may have unique markup not defined in the DITA standard yet be reliably processed in terms of the standard-defined markup.
- The map and topics model, which separates the concern of publication structures (maps) from the concern of content (topics). Maps are simply collections of links to topics. This approach allows the same topic to be easily reused in multiple publications (different maps) or multiple times within the same publication. While not required, this usually leads to an approach where content is managed as many small components that are then combined into different publications as needed.
- The DITA content reference feature ("conref"), which allows any element to be a use-by-reference link to any other element of the same or more specialized type.
- The "keys" indirect addressing feature. When you reuse elements that have embedded links (cross references, content references, etc.) there is the inherent challenge that a link, when used in different contexts, may need to resolve to different targets. Keys make it possible to have reused content that contains embedded links and ensure that the links resolve to the appropriate targets in all use contexts.
Thus DITA documents are inherently interoperable and interchangeable.
- Modularity of content: topics, which contain reusable "modules" of content, and maps, which organize topics into publication structures (books, Web sites, collections, etc.)
- Modularity of vocabulary: A common base plus an unbounded set of additional specialized vocabulary modules that can be combined as needed to satisfy local markup requirements.
- Modularity of processing: Processing that is defined in terms of the vocabulary modules using normal software modularity features (plugins, classes, separate implementation module files, etc.). There is a natural alignment between DITA vocabulary modules and software components that support the processing of that vocabulary. For example, the DITA Open Toolkit uses a plugin model that makes it easy to add support for new vocabulary modules by implementing plugins that extend the base processing to handle processing specific to a new vocabulary module.
While this modularity makes DITA, as an architecture and as a body of supporting tools, very flexible, it also means there are a lot of parts.
DITA satisfies a very wide scope of requirements, from very simple documents with just headings and paragraphs to the most complex task and reference information to learning content with formal objectives, interactive assessments, and so on.
DITA is not a single document type or application. Rather it is a framework and set of building blocks by which specific applications are built while ensuring interoperation and interchange among all conforming DITA content sets and all conforming general-purpose DITA processors. At the same time, you can simply take the DITA document types as provided by the OASIS DITA Technical Committee and start creating documents using your favorite XML editor. While configuration is possible (and encouraged) it is not a cost of entry.
No single DITA user needs every feature of DITA. DITA's modularity features make it possible to pick and choose only the parts you need. Once you start to understand how DITA works generally and get a better understanding of what your current and likely future requirements are you should expect to start doing some configuration of your use of DITA to best meet your local requirements. It shouldn't be that hard to do (and the community is always working on tools to make the mechanics of DITA configuration easier).
The modular design of DITA's markup vocabulary makes it about as easy as it can be to configure your specific use of DITA to meet your local needs while ensuring that any general DITA processor will be able to do something useful with your documents. This enables both interoperation with others at the current time as a well as ensuring that your current documents will be useable by future DITA authors and processors.
Not only are DITA documents interoperable but DITA processors that are implemented to understand DITA's extension mechanisms also end up being very flexible and usually easy to extend in a modular way that mirrors DITA's modularity features. This tends to make DITA systems easier to set up and maintain over time, especially in the face of new requirements.
DITA has a well-established ecosystem of supporting tools, both commercial and free open source, as well as an active and growing community of users, consultants, and tool providers. DITA is well supported by all the major commercial XML editors and XML component content management systems. The open-source DITA Open Toolkit provides the main DITA processing implementation used by the community.
DITA's modularity and extensibility make it well adapted to agile development methodologies because you can get started quickly and then iteratively refine your use of DITA as required, either removing the things you don't need or adding new things to meet your specific requirements.
Because all conforming DITA documents are guaranteed to be interoperable it means you can start simply with the out-of-the-box DITA vocabulary and extend it or constrain it as your understanding and requirements evolve. No other standard XML vocabulary or architecture has this characteristic.
DITA's Unique Approach To Document Types
DITA's base vocabulary is modeled closely on HTML to be familiar to authors already familiar with HTML. As of DITA 1.3, DITA comes out of the box with integrations of MathML and SVG for inline math and vector graphics within DITA topics.
While DITA was originally developed to meet IBM's technical documentation requirements the DITA architecture is completely general and can therefore be used productively for any kind of document. DITA is used in a wide variety of industries and for a wide variety of document types that go well beyond typical technical documentation, including commercial Publishing, pharmaceutical information, standards, training materials, and much more. Because DITA is inherently extensible it can be adapted to almost any document requirement in a way that maximizes the ability to use existing tools and knowledge.
DITA's approach to the markup vocabulary is fundamentally different from all comparable standards. Rather than define a single monolothic document type like DocBook or a small set of related variants based on a common core like JATS, DITA uses a completely modular approach.
With standards like DocBook and JATS, if you create your own document type definition that adds things not defined in the standard then you cannot conform to the standard and there is no reasonable expectation that any processor will be able to operate on your documents. This is because these standards don't provide any way to formally map new element types and attributes to types defined in the base standard. Either you use what is defined by the standard or you don't.
The DITA specialization facility, by contrast, provides a formal, machine-readable mechanism for mapping new element types to base types. This allows anyone to define new markup (new vocabulary) that is defined in terms of the standard-defined vocabulary and that conforms to the DITA standard.
Because the mapping is machine-readable it means processors can process new element types they don't recognize in terms of the base types they're mapped to. For example, you can define a new type of topic that reflects your specific requirements for a particular kind of content, but all general DITA processors will be able to process your new topic type as a generic topic simply because of the specialization mapping from your new topic type to the base topic type.
DITA markup vocabularies are also modular. The DITA standard defines a core base that underlies all specializations and then a set of vocabulary modules for different purposes: specific kinds of maps, specific kinds of topics, and "mix in" elements usable in any map type or any topic type. And anyone can define additional modules that define their own specialized types. As a document type designer you can combine together any sets of modules you want in order to create the specific map and topic types you need for your content.
Pulling existing modules together to create new document types is called "configuration" (because you are simply configuring the combination of existing modules). Defining new vocabulary is called "specialization" (because you are creating new element types and attributes that are specializations of base types). Most users of DITA only ever need to do configuration, usually to leave out the things they don't need.
In addition to adding new vocabulary or simply configuring the set of vocabulary modules you need, you can add constraints that further limit what is allowed in a given document type.
Most of the base content models in DITA are very loose in order to enable specialization and to ensure that the standard can be used for any reasonable content. But in the context of your specific use of DITA you will likely want to make content models more restrictive. The DITA grammar files as provided by OASIS enable configuration using normal techniques for overriding declarations (DITA provides RELAX NG, DTD, and XSD versions of the OASIS-defined grammars).
The DITA standard defines a coding pattern for creating separate constraint modules that further configure the base content models or you can simply define your own grammar files that define your desired grammar rules without trying to maintain the modularity defined in the DITA coding rules. As long as the result produces documents that validate against the unconstrained vocabulary then your grammars are fine. The DITA standard only requires that the result of constraint (or specialization) be no less constrained than the base. That is, you can take away anything that isn't required by the base, you just can't allow anything that isn't already allowed.
This requirement that constraints not be relaxed is what ensures interoperability and interchange of documents and processing. As long as you adhere to this rule you can otherwise do whatever you want in terms of how you configure your DITA document typess or how you define new specializations.
Because you can always create new DITA-conforming vocabularies there is no reasonable documentation requirement that cannot be satisfied within a DITA context while ensuring interoperability. One effect of this aspect of DITA is that it can make DITA the fastest and least expensive route to a new XML solution for your specific XML requirements even when DITA out-of-the-box does not provide the precise markup you need.
DITA Compared to Similar Standards
DITA's closest peer standard is DocBook, which is also designed primarily for technical documentation.
DITA and DocBook address similar sets of general requirements for representing documents but reflect different architectural drivers and approaches. In particular, DITA provides reuse, modularity, and interoperation facilities that were not DocBook requirements.
Another close peer is the JATS (nee NLM) standard, which is optimized for journals and similar types of documents and is mandated by a number of organizations and government agencies, including the U.S. National Library of Medicine.
The S1000D standard, used primarily in the aircraft and military hardware industries, has some similarities to DITA, especially in its support for modular content, but is optimized in different ways and does not provide an extension mechanism comparable to DITA's specialization facility. If you are using S1000D it is likely because its use is mandated in your industry or by your suppliers or customers.
At the level of DITA's base topic vocabulary there is a fairly close match to HTML5,
especially with HTML5's newer more-semantic elements like <article> and
<section>.
Both DITA and DocBook define the same basic kinds of elements for document content: titled divisions or blocks, paragraphs, lists, figures, tables, and inline elements of various sorts. Both have different vocabulary for more specific use cases. For example, DocBook includes detailed bibliographic markup that is not in the out-of-the-box DITA vocabulary (but could be added by anyone who wanted it using DITA's controlled extension mechanism—this is one challenge with comparing DITA to other XML applications: anything in another application can always be replicated to one degree or another, either by defining the equivalent DITA specialization or by including the desired markup as a "foreign" vocabulary).
The real difference between DITA and DocBook-like XML applications is DITA's focus on modularity, reuse, and interoperation, which results in a very different architecture as compared to more traditional XML applications for published documents. Many of DITA's architectural features are unique among well-known XML documentation applications. Interoperation in the way DITA envisions and enables was never really a requirement for DocBook, in particular.
As with DocBook, DITA has a well-established ecosystem of supporting tools, both commercial and free open source, as well as an active and growing community of users, consultants, and tool providers. DITA is well supported by all the major commercial XML editors and XML component content management systems. The open-source DITA Open Toolkit provides the main DITA processing implementation used by the community.
If you have requirements for reuse of content among different publications, the need to manage content as small modules, or to allow different groups within a larger community to have their own markup details while ensuring that their documents can interoperate then DITA is probably the best choice.
More generally, if you need a standard XML application for human-readable documents DITA is probably your best choice unless your documents are journals (in which case JATS is probably your best choice), you are required to use S1000D or a similar industry-specific standard, or you know for sure that you will never need more than what DocBook provides.
While DITA provides many sophisticated features, it can be used in simple and straightforward ways that is very similar to how you might use DocBook to create standalone publications. So even if you don't need all the power DITA provides it may still be the fastest and easiest path to XML-based document authoring and production. If you are looking to migrate from an existing non-standard SGML or XML system to a standard-based system, again DITA is very likely your best choice.
Summary
- An OASIS standard XML architecture for documents intended primarily for human consumption: technical documentation, Publishing, corporate publications, Web sites, etc.
- Driven by requirements for reuse, interoperation, and interchange
- Provides a unique approach to document type (markup vocabulary) design: specialization
- Enables reuse through three main features:
- Separation of maps and topics, where maps are collections of hyperlinks that organize topics into publication structures. The same topic may be reused in any number of maps or any number of times within the same map.
- Element-level use-by-reference within topics (or within maps, although that's less common), the "conref" (content reference) facility
- Indirect addressing that allows the same embedded link to resolve to different targets when used in the context of different maps or in different parts of the same map
- Is well supported by most commercial XML authoring tools and component content management systems.
- Has a robust open-source ecosystem, anchored by the DITA Open Toolkit.
- Has a large and growing community of users.
- Is used by some of the largest enterprises, not just IBM, including hardware and software vendors, commercial publishers, standards organizations, and government agencies.
Resources
OASIS DITA Technical Committee main site: https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
- The "base" edition includes only the base vocabulary modules. This package is the smallest generally-useful configuration of DITA.
- The "technical content" edition adds vocabulary modules and document types designed primarily for technical documentation, including the concept, task, reference, and glossary entry topic types and the BookMap map type. This edition is appropriate for most technical documentation that does not require any learning content.
- The "all-inclusive" edition includes all vocabulary modules and document types, including the Learning and Training.
The DITA Users Yahoo group: https://groups.yahoo.com/neo/groups/dita-users/info. The DITA Users Yahoo group is the main mailing list for the DITA community. It is an appropriate place to ask any DITA-related question regarding DITA authoring, usage, processing implementation, etc.
DITA Open Toolkit: http://www.dita-ot.org. The DITA Open Toolkit is the primary open-source DITA processing framework. It is integrated by most commercial DITA-aware authoring tools and component content management systems. It runs on all platforms. The Open Toolkit is developed and maintained by volunteers.
DITA Community GitHub organization: https://github.com/dita-community. Provides a variety of open-source resources for using DITA, including various DITA Open Toolkit plugins, the "Thunderbird" DITA demo content collection, and the "DITA utilities" project.