Technical Writing and DITA

The production of technical documents such as user manuals is constantly evolving as new technologies become available. Consumers are able to access information in many different forms, including websites, support forums, knowledge base systems, FAQs, and many more. DITA can help writers to meet the challenges of producing technical documents in an increasingly complex global market.

What is DITA?

DITA, or Darwin Information Typing Architecture, is an XML-based system for creating and publishing topic-based content. In 2005, DITA was adopted by OASIS (Organization for the Advancement of Structured Information Standards) as a standard. The OASIS DITA Technical Committee is now responsible for maintaining and updating DITA.

The base feature of DITA is the use of special information types in the form of topics. The DITA language includes both generic topics and specialized topic types, including concept topics, reference topics, and task topics.

Why use topics as the base for DITA? Technical documents such as HTML Help (chm) and browser-based help have a very different structure from books. Traditional book structure includes chapters, sections, and subsections. Authors usually use applications such as Word to create this book type structure. But this structure often doesn’t meet the needs of technical content that may be needed in different outputs and for different audiences.

DITA supports a number of features that are very useful for writers of technical documentation. Below are some of the features that make DITA so valuable for technical communicators.

DITA supports a single source that can output multiple formats

DITA output to multiple files

Recent years have seen many changes in the methods of delivering information to users. In the past, an application or product might have a single manual or user guide. Now user guides can be delivered in many different ways such as Web, HTML Help, PDF, etc. DITA allows you to produce outputs in several formats from a single set of XML files. For example, you can produce an HTML Help file, a PDF file, and HTML files all from a single source.

DITA is topic-based

DITA topics

The primary feature of DITA is the organization of information into individual topics. The topic-based structure allows the writer to organize content into individual chunks of information. A topic is usually a single task, concept, or reference.

Below are some of the advantages of organizing content into topics:

  • Help to promote consistency
  • Allow writers to focus on individual tasks or concepts
  • Can be easier to localize
  • Facilitate the production of multiple outputs from one source

DITA promotes re-use

DITA multiple output

By organizing content into small chunks, it is much easier to re-use content for multiple outputs. When content is structured this way, it becomes possible to freely mix-and-match the content so that it can suit the needs of different users.

DITA also allows the writer to set conditions for the audience, products, version, and platforms. The writer can then use these conditions to produce different outputs for different types of users.

For example, you may need to write a help system for a software application that is available in both PC and Mac versions. The functionality of the application is similar in both operating systems, but there are a few differences between the PC and Mac versions. By using the platform attribute, you can indicate which operating system the topic covers. When you publish your files, you can use the platform attribute to produce documentation for both operating systems.

DITA is flexible

While DITA comes with a set of pre-defined elements, it also offers the ability to customize document structures for specific uses. Specialization is a process where you define new elements and attributes that are based on existing DITA elements. This ability to extend the base elements to other types of documents makes DITA a flexible system that can adapt to the needs of different documentation projects.

The DITA DTD ships with the usual types of elements you might typically use in topics, such as paragraphs, tables, lists, etc. But if you need to customize the structure for your specific needs, you can do that. For example, if you wanted to add an element that contains design notes, you might create a new element called <designNotes>. This ability to customize makes the system very flexible.

DITA separates content from formatting

DITA process

The formatting of the content is in a separate file from the content. This allows the writer to focus on writing content rather than focusing on the formatting of the content. Since the formatting lies in separate files, the output will be consistent, even when there are multiple writers.

DITA reduces translation costs

By maintaining content in one source, it is easier to manage translation costs. For example, if you have one procedure that is used in several types of content (website, HTML Help, FAQs), then you need to translate only one document rather than three documents.

Looking ahead

Single source technologies such as DITA will allow technical writers to use standard processes for creating and publishing technical content. These processes will help writers to be more efficient in meeting the complex documentation needs of today and the future.