A methodology developed by technical writers for technical writers: DITA XML documentation is the markup language of choice for almost 800 companies worldwide, covering a range of industries from software and telecommunications to medical devices and financial services. If you’re looking for a way to publish in various output formats using the same content, reuse more of your content, and maybe even enforce your own rules, then your company might want to join them.
What Is DITA?
DITA is defined in its specification as “an XML-based architecture for authoring, producing, and delivering topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways”. Originally developed by IBM in the early 2000s, DITA stands for Darwin Information Typing Architecture. “Darwin” refers to the naturalist Charles Darwin and his theory of evolution, reflecting DITA’s principles of specialization, inheritance, and adaptation.
DITA topics are standalone, context-free blocks of content, with content types kept clearly separate. There are three main topic types in DITA, all of which are inherited from the base topic type <topic>:
- <concept>: background information that users must know before using the product
- <task>: step-by-step instructions that users need to perform a task
- <reference>: product specifications, commands, or other reference material
You create a document by selecting which existing topics should be reused and referencing them in what’s called a DITA map (similar to a table of contents).
Being an open standard, DITA has no proprietary restrictions. But while you’re not forced to buy a specific tool to use it, commercial XML editors have many features, such as visual editing and validation, that make writing DITA content much easier.
Why Use DITA in Technical Writing?
Here are just some of the advantages of using DITA for your technical documentation:
- Structured authoring improves consistency
As an author edits a DITA topic, it is validated by the authoring tool, which checks the requirements defined in the DITA specification. A topic can’t be saved until it has a title, for example. This validation helps ensure that topics are consistent.
It is also possible to automatically enforce the rules in your department’s style guide. With intelligent style guides based on DITA XML, you can even define warnings or suggestions to be displayed whenever a rule is broken.
- Reusing content saves you time and money
If your content is simply copied and pasted, it must be manually updated everywhere it appears in every single document… This is often time-consuming and prone to error.
With DITA XML documentation, content reuse means that an author only needs to make changes in one place. The content is then automatically updated everywhere it is reused. Writing the same information just once not only saves time but also reduces maintenance and translation costs.
- Authors can focus on the content
XML-based authoring allows content to be separated from presentation, with DITA markup using semantic elements that convey the meaning of their content: They describe what the information is and not how it will appear.
For example, a piece of code within a sentence is marked up with <codeph> (code phrase): It’s irrelevant whether the code will be in gray, or which monospaced font will be used. A document’s appearance is determined during an automated publishing process, allowing technical writers to concentrate solely on the actual content.
- Flexibility through single-source publishing
The same DITA content can be used to produce multiple deliverables in different formats, such as a PDF file, a website, and an e-book. Profiling allows you to apply certain conditions during processing to adapt the deliverable to the target audience or platform. So paragraphs intended for system administrators can be omitted from a user guide or different instructions shown to a Linux user.
- DITA XML Documentation adapted to your needs
Using the inheritance principle, you can define new topic types or domains by adapting or extending existing ones. Called specialization, this feature allows you to create something new by simply defining how it differs from what it was inherited from. It is also possible to restrict which attributes are available for a certain element, and much more.
- Collaboration made easy
DITA files can be used with version control systems like Git or in a CMS to enable multiple collaborators to work on the same documentation project. If you use Oxygen XML Editor, you can install their free Git plug-in so that, whenever someone edits a topic in Oxygen, they can push the changes to the GitHub repository storing your DITA content. That way, others working on the project get the updated version too.
Are you thinking of migrating to DITA but don’t know where to begin? Learn DITA XML for free to get started.
