Introduction to DITA

What is DITA?

The Darwin Information Typing Architecture (DITA) is an open standard for Extensible Markup Language (XML) that is used to create, structure, and distribute content. DITA was developed at IBM. But its widespread adoption can be attributed to DITA becoming an open standard. At its essence, it's a methodology for writing basic building blocks of content that can be organized and reused easily across platforms.

What does "DITA" mean?

"DITA" stands for Darwin Information Typing Architecture.

"Darwin" refers to the Charles Darwin, who developed the scientific concept of trait inheritance. In DITA, this refers primarily to the parent-child relationships of topics. A child inherits traits, or attributes, from their parent.

Information Typing does not refer to actually typing information on a keyboard, but rather to the categorization of information. DITA uses a structured approach to authoring, including defined topic types and elements. For example, a concept topic conveys conceptual information and a task topic contains procedural information.

IBM defines DITA in the following way:

The Darwin Information Typing Architecture (DITA) is an XML-based, end-to-end architecture for authoring, producing, and delivering technical information. This architecture consists of a set of design principles for creating “information-typed” modules at a topic level and for using that content in delivery modes such as online help and product support portals on the Web.

For more information, see DITA.

History of DITA

DITA was created by IBM, in 2001, to replace their clunky and difficult IBMDoc format. Once IBM realized the benefits of standardization for the technical writing industry, IBM gave DITA to the Organization for the Advancement of Structured Information Standards (OASIS). In 2005, OASIS publicly released DITA.

How is DITA used today?

The reason DITA has spread across many industries is due to it being an open standard. Imagine how different the internet would be if HTML had not been open to the public.

Software and technology customers frequently use DITA to document their products. Manufacturers in many industries use DITA, for example manufacturers of hardware, semi-conductors, and medical devices. DITA is also used by e-learning companies, financial companies, policy and standards organizations, and many other industries.

Adopting the DITA standard has allowed these industries to make their document production and maintenance much more efficient and effective.

Let's look at an example of how this works.

Suppose you produce two models of some product, Model A and Model B. While the two models have some differences, Models A and B share a lot of the content. To write user manuals for each model using DITA, you create individual topics, such as an Introduction, Product Safety, Instructions, Product Specifications, and so on.

To create a user guide for each product, you create a separate map for each, Model A and Model B, and add the topics that are specific to each model in order to build a table of contents for each. Both models share, that is, reuse, some content in each manual while some content is specific to each model. The idea is that you write the shared content only once, and then both models can use the same topics. Then, when your guides are complete, you can publish to multiple media outputs with the push of a button.

Benefits

DITA has many benefits to both business management and technical processes.

BenefitDescription of ProblemBusiness Management BenefitsTechnical Benefits
Content ManagementContent is stored in many "silos" and is difficult to find, update, or collaborate on.DITA systems provide a single content repository that all team members can access. Multiple users can search, author, edit, review, and publish using a single source, so everyone's on the same page. DITA has highly effective search capabilities with taxonomy and metadata. All changes are tracked so content is easy to find, use, and manage.
ReuseContent creation is expensive and labor intensive. Reusing content often involves copying and pasting, which can result in errors.Topic-based authoring in DITA makes it easy to reuse content. Reusing content ensures consistency in publishing outputs and also reduces costs.DITA enables you to reuse content effectively without copying and pasting. You can easily update content in just one place and generate a global update.
PublishingPublishing content to multiple platforms requires extensive styling work. Proprietary systems limit publishing options.DITA content can be published to many different media formats and devices with the push of a button, reducing the cost of publication that's typically spend on formatting by 30-50%, as multiple studies show. For more information, see Formatting Costs.DITA applies formatting when content is published, which eliminates the need for manual formatting and results in consistently formatted outputs for multiple media.
Translation and LocalizationLocalizing content is costly and can delay time to market.With DITA, you can create translation packages of the content that you need and not content that has already been localized, significantly reducing translation costs.easyDITA tracks which content is up to date and because content is broken into smaller topics, localization is much more manageable.
Interoperability and ScalabilityDocuments created in proprietary formats cannot be opened or are not supported by other software.DITA is an open standard, which means that content created in DITA can be transferred to other systems without a complex, costly conversion process.DITA is an XML based standard, which is both human- and machine-readable. This enables connections with other software, like WordPress, Mindtouch, Sharepoint, and other applications.
WorkflowIt's difficult to track and collaborate on large content development projects throughout an organization. Writing content to support products often comes at the end of the product development cycle.In DITA, content development aligns with agile product development because content is broken into smaller topics. Simultaneous content development and reuse means documentation can be developed and released more quickly.DITA systems provide a mechanism to assign and track work using workflows. A collaborative authoring and review process in a single-source increases efficiency.

Information Typing

DITA is built on a process of information typing that you probably already use when you break off conceptual content, procedural content, and reference content into their own sections in a larger document. DITA breaks your documentation down into information types called topics. Topics focus on a single subject that can stand alone as a self-contained chunk of content. This means that each topic only contains relevant information and should not require additional resources to understand the information. By organizing your writing this way, you enable greater reuse opportunities and provide easily understandable information to your audience.

DITA content is broken down into three main topic types:

Topic TypeDescriptionExample
ConceptProvides conceptual information about something. Answers the question "What is...?"Introduction to your Toaster
TaskProvides procedural information that tells you how to perform a task. Answers the question "How do I...?"Cleaning your Toaster
ReferenceProvides supporting information, typically in tables, such as specifications.Toaster Technical Information

Concepts

At its essence, a concept topic answers the question, "What is...?". Concept topics provide contextual information that is needed to understand a product or system functionality as a whole.

Conceptual topics help readers tie their existing knowledge to a new product or task. If you provide instructions for "Installing the OS-XT29", your reader might wonder what the OS-XT29 is, how it differs from other versions, what it does, and more. Concept topics provide those missing pieces of information.

This concept is used as an introduction for a toaster manual:

Classic Toaster Introduction

The Classic Toaster™ is the one-of-a-kind, classic breakfast machine you wanted since you were old enough to eat solid food. Have perfect slices of delight with your favorite jam or butter. Easily achieve exquisitely toasted bagels with a push of a button.



Tasks

Task topics answer the question "How do I?". They provide step-by-step information that tell a user how to do something. Task topics are the heart of DITA content. They provide the core information readers are looking for in documentation. That is, task topics provide information users need to achieve their goal, for example, configure something. Concept and reference topics supplement task topics with information related to the task topic content that doesn't belong in the task topic itself.

The basic task structure goes as follows:

  1. Title: Name of task
  2. Pre-requisite: What the reader needs to know prior to performing the task
  3. Task steps: Step-by-step instructions
  4. Result: Outcome of completing the task
You can use some or all of this structure to establish a content standard. Having a title and steps could be mandatory but a pre-requisite could be optional. There are additional elements that can be added to a task, such as step results or sub-steps.

Here's an example of a task topic in the toaster manual:

Toasting Bread

Toast bread to the perfect doneness using your Classic Toaster.

Pre-requisite

You will need: Sliced bread, the toaster, an outlet, and a spread (if desired).

Task Steps

  1. Plug toaster plug into outlet.

  2. Insert sliced bread into bread holes located at the top of the toaster.

  3. Adjust the timer for how long you want to cook the toast.

  4. Press the lever down.
  5. When toast pops up, remove from the toaster and place on a plate.
  6. Use desired spread on top of toast.

Result

Your toast is ready. Eat it before it gets cold!

References

Reference topics provide supplemental or technical information on a product. You can use reference topics to provide information such as product dimensions, equipment lists, parts lists, required tools, or the functions of a product or service.

Here's an example of a reference topic used in a toaster manual:

Classic Toaster Technical Information

Classic Toaster dimensions, weight, and other technical information.

Table 1. Classic Toaster Technical Information
NameValue
Capacity1 or 2 slices
Output per hour30 slices
Loading (kW)2.2
Dimensions (cm)36 x 21 x 22
Weight (kg)4.25
Slot width28mm
MaterialsCast aluminum ends, stainless steel body

Maps

The individual, self-contained topics are typically compiled into a map for publication. Maps enable you to create deliverables by adding references to topics or other maps. Think of a map as a book binder and topics as pages. You have a binder (map) and fill it by adding pages (topics). You can also add other maps to create large publications. By creating maps for individual publications, you can ensure that the right content goes to the right audience.

Below we have two models of toasters: the Classic Toaster™ and the Lightning Toaster™. The left column shows all the topics related to both toasters. The map for each toaster model includes only the relevant information so the reader doesn't need to wade through unrelated content.



Reuse

One of the major advantages of DITA is the ability to reuse content. There are two main forms of reuse in DITA, topic reuse and topic element reuse. Topic reuse is when you reuse an entire topic and topic element reuse is when you reuse an element that belongs to a topic, for example, a paragraph, note, or step.

DITA uses topic-based authoring to enable greater reuse opportunities. For example, these five publications share several reused topics:

You can also reuse a specific topic element, such as a note. For example, if there is a standard disclaimer or warning that is used in all product manuals, you can write the warning once and reuse it in other documents.

The level of reuse can become very granular; paragraphs and even phrases or words can be parsed and reused across topics.

There is a big difference between reusing content and copying and pasting content. When you copy and paste content, there are duplicate files with the same information. When the information is updated in one, the changes are not reflected in the other files. Reuse, on the other hand, stores content in just one file. When updates are needed, you can update that one file and other files reusing it are also updated. This ensures consistent documentation and reduces the time and effort needed to create and update content.

Publishing

It's common for users to consume information with increasingly varied devices such as mobile phones, tablets, and computers. One of the advantages to using a standard like the XML-based DITA is the ability to publish to many different output formats. Since XML is both human-readable and machine-readable, there are many different publishing possibilities for DITA content.

DITA works with most commonly used publishing engines, such as WordPress, Mindtouch, Sharepoint, and others.

DITA separates styling and formatting from the authoring process. Styling is applied when documents are published, using plugins to ensure your content is beautifully and consistently styled. With the click of a button you can publish your content to multiple outputs and apply styling specific to each. When you write your content in DITA and publish to both mobile and browser-based outputs, you can apply styling to provide a great consumer experience in both outputs.

Content Management Systems (CMS)

Content Management Systems (CMS) enable you to store, organize, author, review, and publish content. While DITA offers many features, it is typically paired with a CMS that allows content managers to easily work on the content. When you have all your content broken into manageable pieces in a central system, you can do a lot more with it.

Many content development teams work in siloed environments, meaning if you're looking for a specific piece of information, it may be in an individual's files, so content is hard to find and collaborate on.

A CMS enables you to do all authoring, reviewing, commenting, approving, and publishing in a centralized database. Content is better organized and easily searchable so it can be reused in multiple publications.