Darwin Information Typing Architecture

Note: This blog post has been migrated, and was originally published on 21st February 2017.


Darwin Information Typing Architecture (DITA) is an XML-based open standard for structuring and publishing technical documentation. It is a popular standard for creating topic-based minimalist documentation sets with the goal of delivering what customers actually need to know, when they need to know it.

The standard is managed by the Organization for the Advancement of Structured Information Standards (OASIS) DITA Technical Committee. It first started as a proprietary standard at IBM with the goal of creating content that could be efficiently reused in multiple output formats.

However, DITA is also known for being restrictive and best suited to highly structured products. Could it really be useful for an evolving software product, developed in an Agile environment?

The answer, perhaps surprisingly, is yes.

DITA builds on the fundamental principle that all technical authors must follow. That is, the aim of the documentation is not to describe how the product works but to help the users of the product to accomplish their goals.

It does this by advocating task-orientated documentation as you would expect, but goes further and expects authors to split the user’s tasks into mental and physical steps. The reason for this is to separate the information required for decision-making from the actual actions taken to do the task. By separating the information in this way, and by knowing the audiences they are writing for, authors can write very clear step-by-step instructions, conceptual information and reference material which can then be assembled into various documentation products for the different audiences.

The distinct nature of each type of information is captured in the four DITA Topic Types — Concept, Task, Reference and Glossary. These types can be specialised to meet individual company or industry requirements without losing their basic properties which are always inherited, hence the reference to Darwin in the name.

DITA Topics visualised

As well as the topics themselves, authors must write DITA Maps to arrange the content of topics to form documents such as online help topics, user guides and reference manuals. Content references (known elsewhere as snippets) and nested topics can be used to reuse content within topics to avoid duplication.

Here is an example, from dita.xml.org, to show how a DITA Maps are used to produce different documents from different combinations of the same set of source topics.

DITA Maps used to produce different documents

DITA tools which create the necessary code and help build the map files are available but these are expensive and difficult to learn. We are unlikely to adopt this standard any time soon.

However, we could separate our topics into the DITA types of Task, Concept, Reference and Glossary. This would have several benefits for ourselves and our users. Users would find the information they need more quickly and have to read less to achieve their goals. It would also be easier for the documentation to keep pace with a changing product.

In this Agile environment, the ability to divide content sensibly into small, maintainable, reusable chunks makes perfect sense.

Like what you read? Give Jonathan Law a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.