DITA XML: Exploring the Darwin Information Typing Architecture Standard and Its Use Cases 

DITA XML is likely to be a missing piece for companies struggling to manage lavish amounts of content they produce, such as manufacturing instructions, user manuals for goods, internal and external training materials, marketing documents, etc.

Why is DITA a golden standard for document management, and how can you use it to maximize content reuse and perfect traceability of your elaborated content tree? A product owner of our custom DITA-based software for enterprises will guide you through the topic, unveiling the nuts and bolts of DITA. 

What is XML?

XML is a text-centric markup language with a set of tags to annotate and interpret data. It was designed as a foundational format for storing data as structured information. Given its focus on structurality, XML is usually used to manage technical content. XML files can be processed by programs that interpret marked-up data, such as XML validators and XML editors.

What is DITA XML?

Darwin information typing architecture (DITA) is an open-source XML-based content standard for structured authoring and organizing topic-oriented information. Thanks to elaborated content reuse mechanisms at its core, it facilitates all documentation-related tasks, such as authoring, editing, reviewing, translation, localization, and publishing, and empowers companies to produce multiple output formats from a single piece of DITA content. The standard can be leveraged to create and maintain any highly sophisticated content trees with numerous repetitive elements.

Consider DITA XML adoption if you constantly encounter these struggles

DITA addresses a slew of documentation-related hurdles: 

• Unstructured documentation that hinders effective reuse of the existing content 
• Inconsistent content with duplicates scattered across the organization
• Inability to produce several output formats from one source item at a time
• Lack of linkage between related documents 
• Human error-prone processes due to inadequate automation
• Difficulties with seeing a complex content tree as a whole
• Time-consuming documentation updates 
• Pricey content maintenance, localization, etc. 

With DITA XML authoring, organizations from various industries can gain a single source of structured dynamic content components they can reuse infinitely without constantly pouring money into the system. 

It makes DITA-driven solutions a game-changer for two types of companies:

• Enterprises with stacks of external and internal user guides, marketing materials, training courses, reports, etc. 
• Medium-size businesses that expect to reach the enterprise scale and want to manage their documentation right from the start to prevent stumbling blocks down the road. 

LEGO in the world of documentation management tools: fundamental principles of DITA-based systems

The powerhouse behind the DITA standard lies in four dimensions — modularity, inheritance, reusability, and traceability. Let’s explore each of them and the features they go hand in hand with. 

Granular modularity

When companies put document organization on the back burner, they usually create every new piece of content from scratch or copy repeating parts from the existing files at best. And when minor changes to a paragraph used across multiple files have to be made, the documents need to be edited separately. Such an approach fails to provide a clear vision of the overall content structure and hinders the efficient reuse of the existing materials.

DITA standard, with its topic-based authoring, completely rewires the management of educational, marketing, and technical content. Instead of treating a document as an inseparable whole, all files are divided into small chunks of unique information called ‘topics’, that empower authors and translators to manage content at a granular level, down to the chapters, paragraphs, phrases, and even words. 

DITA architecture entails several topic element types:

• Glossary entry topics provide brief definitions of single terms. 
• Glossary groups are the result of uniting separate glossary elements together. 
• Task topics cover how-to procedures.
• Reference topics link different elements within the system and may include data for supporting tasks, for instance, by providing equipment and product specifications.
• Concept topics encompass what-is content, but they’re broader than glossary entries and specify background information for other elements, such as tasks or references.

Thus, topics are the building blocks of your content tree. Several topics can be combined into a DITAmap file, creating a document-like entity. Proceeding with the LEGO analogy, a map is a step-by-step instruction that comes with the builder set and specifies how to match the pieces to get what’s shown on the package.

Let’s get back to the situation when an author needs to make identical edits to a bunch of files. For example, when a company updates a production line procedure, the changes must be reflected across all related manuals, safety instructions, and process guides. Manually performing this repetitive task would be a waste of time and could lead to inconsistencies. With DITA and its automated publishing, a content manager just needs to change the source topic, and edits will be automatically propagated to all the documents containing this topic.  

Mandatory inheritance

Although modularity provides DITA users with a robust and consistent way to create dynamic content components that can be easily reused, it’s not a cure-all. 

Having a lot of elements you can mix and match however you want doesn’t guarantee hitch-free documentation management. 

That’s why the concept of inheritance is vital for DITA-based solutions. By default, any DITA-driven system implies that there are parent and child elements that follow a corresponding hierarchy — parent components always cascade down to related child elements. Such an approach: 

• Provides users with an easy-to-grasp content tree at the scale of a whole organization and its separate departments. 
• Simplifies and speeds up the creation of new content, as technical writers can build on top of existing files instead of writing from scratch. 

Thereby, the inheritance principle facilitates reusability and traceability within the system. 

Extensive reusability

DITA standard is known for its diverse range of reusable elements and customizable metadata. 

Depending on the maturity of the DITA-driven software, the list of components you can limitlessly repurpose may include:

• Keywords
• Media objects
• Whole topics or subtopics
• Maps or submaps

Reusable elements underpin multichannel publishing, when the same piece of content can be adapted for numerous types of documents, including internal technical documentation, client-targeted marketing materials, and product descriptions for end users. Moreover, DITA enables publishing in different output formats, such as PDF, HTML, Web Help, XHTML, EPUB, and more.  

Even when used within one language, reusable elements are beneficial enough. But they show their full value and cost-cutting potential in translation and localization tasks. If a piece of content was already translated for another document, authors can reuse it to speed up translation and decrease its cost. 

Metadata is another vital element of any DITA-powered solution. It is attached to topics and maps and allows users to assign tags to reusable elements and glimpse the document’s content without opening the XML file. These annotations streamline searching within the system, making this feature a blessing for companies with highly sophisticated content trees.  

Moreover, you can customize metadata according to your needs. For instance, a machinery manufacturer can create a specific metatag to mark the files related to discontinued models.  

In-depth traceability

The more you hone transparency within your content system, the more value you can gain from your documentation. How do DITA’s mechanisms champion traceability?

• Solid linking and cross-referencing capabilities within the system to keep related modules connected even when the objects, or ‘sub-topics’, are moved within topics and to other maps. 
• Hierarchical structure with a history view feature to track changes in the smallest chunks of your content.

Thus, every document check-in is recorded, and each change in an XML file is shown in a new document version. This way, users can:

• See all the document versions 
• Compare the current XML file with any of its previous versions
• Check the author of the changes
• Select any version of the document and restore it

Challenges you may face when adopting DITA

Switching to a structured authoring paradigm from an unstructured one is a tough nut to crack. The DITA satisfaction survey unveils the harsh reality that not every DITA project is a hit. Actually, 83% of them end up as duds.  

There’s no magic formula for success, but here’s the list of possible obstacles you should be aware of: 

• Absence of a coherent content strategy. Adopting the DITA XML standard without a clear vision of how you are going to capitalize on its strengths to get your documentation in order is like ordering an Uber without setting a destination. You should think of the business and functional requirements for the new tool, reuse guidelines, etc., to ensure positive ROI. 
• Reluctance to undertake the content preparation stage. One of the best features of DITA is the ability to generate multiple output formats. However, to build on top of this advantage, companies have to unify their heterogeneous documentation first. In such cases, content conversion from DOCX, HTML, PDF, etc. to DITA format is mandatory at the pre-adoption stage, which involves extra time and expenses. 
• Relatively complex UI that requires running DITA XML training. Initially, the standard was created specifically for tech writers, so as a business owner, you should consider investing in employee training. Partnering with a stalwart tech vendor that offers hands-on DITA workshops as part of their services can lighten this burden and make software adoption painless for your staff.
• Overall cost of DITA adoption. While the DITA standard itself is free, its implementation may cost a small fortune. A powerful enterprise-targeted solution is worth its money, but you should meticulously calculate your decision to ensure the software can bring the much-expected benefits. 

How can you eliminate and prevent these hardships?

Ways to reap the benefits: DIY approach vs. vendor software

Since its release in 2005, DITA has been an up-for-grabs open standard. However, a plethora of DITA-based vendor solutions have also emerged, putting companies in front of a dilemma: whether to take advantage of free tools or opt for a DITA-powered component content management system (CCMS).

Leverage free, open-source options to craft your own budget-friendly software

DITA standard itself isn’t enough to take full advantage of structured authoring. A company will also need a free XML editor and a publishing engine, such as DITA Open Toolkit (OT) or DITA XMLmind, to name a few. These open-source and vendor-independent processors became a foundation for numerous DITA and XML-based tools. 

Following DITA OT documentation and guidelines, you can customize the software to match your specific documentation management needs without breaking the bank. 

Yet, while embracing the thrill of the DIY approach, keep your eyes wide open to its challenges:

• Readiness to invest time in crafting custom software on your own
• Need for profound in-house DITA expertise to ensure successful adoption 
• Ability to handle maintenance issues, as it will be a set of tools, not a standalone solution

We suggest this way to companies that are already familiar with the specifics of managing tech documentation, don’t have a strict deadline for their DITA project, but need to take into account budget limitations.  

Bank on customizable SaaS software to save time on development and fine-tuning

Enterprise authoring solutions also rely on the same open-source publishing engine – DITA Open Toolkit. However, driven by market competition, each vendor tries to take basic DITA OT capabilities to the next level. These efforts lead to covering major pain points of free tools:

• All-in-one software for DITA authoring, editing, and publishing that simplifies collaboration between authors, reviewers, translators, etc.
• User-friendly interface with drag-and-drop functionality and other intuitive features decreases the employees’ resistance to adopting new software
• Time saving thanks to implementing extensive out-of-the-box functionality 
• Custom features can be unlocked when upgrading to a higher-priced plan
• Unlimited fine-tuning potential to match your specific needs and documentation management processes with the vendor’s battle-tested DITA expertise

Moreover, a SaaS component content management system may provide unique functions backed by the vendor’s expertise in trailblazing technologies. 

Instinctools’ DITA-based software: how DITAworks Webtop stepped up tech documentation management for a large Danish manufacturer

The market of DITA-powered solutions keeps evolving, and spotting the most beneficial option can feel like hunting for treasure — except the treasure might be elusive. Companies eager to leverage the DITA standard often risk sinking their budgets into software that turns out to be outdated and ill-suited to their needs, so, instead of capturing the right tool that delivers value, they get an expensive lesson.

That was the situation our client got caught up in. A Danish manufacturer had already adopted SaaS DITA technical documentation management software, but it misfired and turned out to be ill-performing, inflexible, and lacking vital functionality.

Therefore, when DITAworks Webtop appeared on the client’s radar, they decided to give DITA adoption another try and switch to our feature-rich software with: 

• Support of different DITA processors. Our product relies both on DITA OT and DITA XMLmind to ensure materials are published in less than one second. 
• Broad search capabilities. In addition to searching by title, phrase, and full text, users can find files and their components using conditional processing (CP) tags and metadata.

• Custom features. Authors and translators can set any folder as a root in the current working context to eliminate the pain of re-opening ‘folder-in-a-folder-in-a-folder’ when operating in the same folder for a long time. Also, users are allowed to isolate their current working context, for example, when several linguists translate the same topic simultaneously.

Jeanine Shepstone, Senior Technical Writer at the client’s company, outlines the project’s progress and outcomes:

Instinctools used our outline spec to create a user-friendly and robust custom interface. They not only implemented the specification, but also added all the small, helpful HMI elements that made the interface a pleasure to use. We can now work more intelligently with our documentation. The robust system has also allowed us to handle challenges quickly and effectively. The continuing excellent service from Instinctools has kept us running well. 

Bear the low-hanging fruits of DITA-driven documentation management

DITA-powered software is a not-to-miss opportunity if you want all bits of your content to bring value while decreasing the overall cost of document-related processes and accelerating them. However, you may need expert guidance to evaluate the benefits and risks of DITA adoption, choose the appropriate software, set fact-based targets for your DITA project, and make sure the solution fits the bill.

FAQ