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.
In DITA, content is broken down into self-contained topics, then arranged in content maps, and published to multiple media outputs.
Let’s look at an example of how this works:
You produce two models of toasters, the Classic Toaster and the Lightning Toaster. While the two products have some differences, a lot of the content in the documentation is shared. To write a user manual for each toaster using DITA, you create individual topics, such as an Introduction, Product Safety, Instructions, and so on.
To create a user manual for each product, you create a map for each publication and add the topics to build a table of contents. Some content is shared, or reused, in each manual. When your manual is complete you can publish to multiple media outlets with the push of a button.
What is DITA?
DITA was developed at IBM, but its widespread adoption can be attributed to DITA becoming an open standard.
What does DITA stand for?
DITA stands for Darwin Information Typing Architecture.”Darwin” references the scientist Charles Darwin who developed the concept of evolution. In DITA, this refers primarily to the parent-child relationships of topics. A child inherits attributes from their parent.
“Darwin” references the scientist Charles Darwin who developed the concept of evolution. In DITA, this refers primarily to the parent-child relationships of topics. A child inherits attributes from their parent.
Information Typing does not refer to 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.
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.
So, what is DITA?
DITA is an XML-based standard for creating, structuring, and distributing content. DITA essentially provides a model for authoring in smaller building blocks of content that can then be organized and reused in many different publishing outputs.
Let’s look at the toaster manual example again. Rather than writing two long documents to create product manuals for each toaster model, the content is constructed in different types of building blocks that can be reused in different publications. Introduction, Product Safety, and Instructions are three topics. While the Introduction topic for each toaster model may differ, the Product Safety topic could be reused in the publication map for each product manual.
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, including manufacturers of hardware, semiconductors, and medical devices to name a few. DITA is also used by e-learning companies, financial companies, policy and standards organizations, and many other industries.
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 is built on a process of content typing that you probably already use when you break off conceptual content, procedural content, and reference tables into their sections in a larger document. DITA breaks your documentation down into content types called topics. Topics focus on a single subject that can stand alone as a self-contained chunk of content. 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:
|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|
At its essence, a concept topic answers the question “What is…?” A concept topic provides contextual information that is needed to understand the documentation as a whole.
Conceptual topics provide readers with the information needed to 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 to a toaster manual:
Classic Toaster Introduction
The Classic ToasterTM 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 provide step-by-step information that tells a user how to do something.
There is a standard structure for tasks that eases collaboration by multiple authors. The basic task structure goes as
- 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).
You now have tasty toast.
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 user guide.
Classic Toaster Parts
|Capacity||1 or 2 slices|
|Output per hour||30 slices|
|Dimensions (cm)||36 x 21 x 22|
|Materials||Cast aluminum ends, stainless steel body|
The individual topics you create can stand alone but are typically complied into a map for publication. Building a map is similar to building a table of contents. 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 ToasterTM and the Lightning ToasterTM. 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.
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 element reuse.
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 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, elements, 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.
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 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.
References and resources