This primer is designed to prepare content creators to jump into the world of DITA.
Darwin Information Typing Architecture (DITA) is an open standard for XML that is used to create, structure, and distribute content. At its essence, it’s a methodology for writing basic building blocks of content that can be organized and reused easily across platforms.
Learn the basics of the Darwin Information Typing Architecture (DITA).
In DITA, content is broken down into self-contained topics, then arranged in content maps, and published to multiple media outputs.
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.
DITA has many benefits to both business management and technical processes.
|Benefit||Description of Issue||Business Management Benefits||Technical Benefits|
|Content Management||Content is stored in many "silos" and is difficult to find, update, or collaborate on.||DITA provides a single document 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.|
|Reuse||Content 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 find and 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.|
|Publishing||Publishing 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.||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 Localization||Localizing content is costly and can delay time to market.||DITA creates translation packages of the content that you need and not content that has already been localized, significantly reducing translation costs.||DITA tracks which content is up to date and because content is broken into smaller topics, localization is much more manageable.|
|Interoperability and Scalability||Documents 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.|
|Workflow||It'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 provides a mechanism to assign and track work using workflows. A collaborative authoring and review process in a single-source increases efficiency.|
DITA content is broken down into three main topic types:
|Concept||Provides conceptual information about something. Answers the question "What is...?"||Introduction to your Toaster|
|Task||Provides procedural information that tells you how to perform a task. Answers the question "How do I...?"||Cleaning your Toaster|
|Reference||Provides supporting information, typically in tables, such as specifications.||Toaster Parts|
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.
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:
- Title: Name of task
- Pre-requisite: What the reader needs to know prior to performing the task
- Task steps: Step-by-step instructions
- 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:
Toast bread to the perfect doneness using your Classic Toaster.
You will need: Sliced bread, the toaster, an outlet, and spread (if desired).
- Plug toaster plug into an outlet (Fig. 1).
- Insert sliced bread into bread holes located at the top of the toaster.
- Adjust the timer for how long you want to cook the toast.
- Press the lever down (Fig. 2).
- When toast pops up, remove from the toaster and place on a plate (Fig. 3).
- Use desired spread on top of toast (Fig. 4).
Your toast is ready. Eat it before it gets cold!
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
|Capacity||1 or 2 slices|
|Output per hour||30 slices|
|Dimensions (cm)||36 x 21 x 22|
|Materials||Cast aluminum ends, stainless steel body|
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.
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.
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)
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.