Learning about DITA

The OASIS Open Darwin Information Typing Architecture (DITA) is an XML documentation standard that aims to make it easy for technical writers to reuse and remix content to create new kinds of documents. If you copy and paste content between documents to make new kinds of documents, that's a great use case that DITA is designed to solve.

Recently, I spoke with Radu Coravu, a DITA XML expert working for oXygen XML Editor, about working on documentation with DITA:

What kinds of tasks or documents is DITA best used for?

Most of our users who work with the DITA XML standard are technical documentation writers. Some of them document software products and some of them document real world products like kitchen appliances, camping equipment, and so on.

Our clients have the need to reuse content in their technical documentation. As opposed to copy-pasting, content reuse brings consistency and allows the use of content topics or elements as building blocks (like LEGO) to faster create documentation. We have clients who translate to lots of target languages and content reuse also helps to lower the translation costs which are quite considerable for companies which produce lots of documentation.

They also need to produce multiple user manuals from a single set of DITA XML files. For example, the use of DITA XML filters and profiling attributes allows us to produce—from the same DITA Map—documentation for our many Oxygen XML tools like XML Editor, XML Author, WebAuthor, and so on.

And of course, technical writers need to produce multiple output formats, usually HTML based and PDF.

What are the different kinds of DITA documents?

Technical documentation writers work on the documentation with lots of imposed rules, the DITA XML vocabulary imposes a set of used element names, they may also have style guides explaining the tone of voice (imposed using a terminology checker) and various company specific rules (imposed by Oxygen during automatic validation using Schematron).

The DITA XML standard has three base information types: Concept, Task and Reference. The Information types section in our DITA Style Guide written by Tony Self explains how each should be used.

The DITA XML standard does not impose these information types, there are projects "in the wild" in which writers have decided to only use the DITA "topic" base information type for all their content instead of using more specialized information types like "concept" or "task."

So the use of the Concept, Task and Reference information types is not required, but it is a best practice which will ensure more consistency in your writing and content reuse. If you decide to follow this best practice, whenever you want to write a new DITA topic you need to decide its information type, if for example you want to describe a certain concept or you want to write a procedural task for accomplishing a certain goal. Identifying the information type in the DITA Style Guide again helps with deciding which is which.

How do technical writers use DITA to create documents?

Technical writers create and maintain one or multiple DITA Maps which are the table of contents of the publication.

Then they create the DITA topic types (Topic, Concept, Task, Reference) which are the building blocks of the publication. A topic may be reused in multiple parts of the publication or using applied filters it may have different content depending on the publication which is produced.

There are also smaller reusable elements (like product names, tables, lists, or notes) which may be reused multiple times in the project.

Using these building blocks you can create from the same set of XML files documentation user manuals and make them available to users in a variety of formats like HTML, PDF, EPUB, and many more.

What's an example of a document or use case that is easy to do in DITA that is really hard to do with a traditional desktop word processor?

If you store the entire documentation in a single word processor document, you cannot obtain quality web-based output from such a document. That's because when publishing for the web, you need to have a website with multiple web pages.

This modularity of the DITA XML standard allows you to work and describe your content in small topics which will be mapped (usually one to one) to the generated HTML documentation. The DITA XML standard also provides support to define metadata used in the published output.

The content reuse potential of the DITA XML standard leads to consistent content and the profiling/filters capabilities make it possible to create documentation for similar products from the same set of files.

Thank you to Radu for this insightful discussion about using DITA for technical writing. To learn more about editing DITA XML with Oxygen, Resources for learning DITA with Oxygen includes lots of great information including documentation, guides, and past webinar recordings.