DITA XML keeps coming up in conversations about documentation management, and for good reason. When technical content grows past a handful of manuals, the cracks in unstructured workflows get expensive: duplicated effort, inconsistent outputs, version-control chaos, manual rework across channels… Structured authoring and XML solve these problems at the architecture level.
This article walks you through the basics of DITA structured authoring and supplies you with DITA guidelines. As the team behind DITAworks, an enterprise-scale DITA platform, we spill the tea on the topic.
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. DITA (Darwin Information Typing Architecture) builds on this foundation, adding a topic-based structure specifically designed for technical writing and content reuse.
What is DITA XML?
DITA stands for Darwin Information Typing Architecture and 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 (PDF, HTML5, EPUB, etc.) 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
As DITA provides a single source of structured content that scales across products, languages, and output formats, implementation of a coherent DITA structure solves a slew of documentation-related hurdles for companies producing extensive technical documentation:
- 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.
DITA architecture: four principles of structured content management and DITA writing methodology
Understanding DITA basics starts with four dimensions — modularity, inheritance, reusability, and traceability. Let’s explore each dimension of the DITA framework 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.
The following DITA documentation examples illustrate the topic element types that DITA XML architecture entails.
- Glossary entry topics provide brief definitions of single terms.
<!-- Glossary entry topic -->
<glossentry id="dita-definition">
<glossterm>DITA</glossterm>
<glossdef>An XML-based open standard for structuring,
authoring, and publishing technical content.</glossdef>
</glossentry>- Glossary groups are the result of uniting separate glossary elements together.
<!-- Glossary group topic -->
<glossgroup id="xml-standards-glossary">
<title>XML Standards Glossary</title>
<glossentry id="dita-definition">
<glossterm>DITA</glossterm>
<glossdef>An XML-based open standard for structured authoring.</glossdef>
</glossentry>
<glossentry id="xslt-definition">
<glossterm>XSLT</glossterm>
<glossdef>A language for transforming XML documents into
other formats.</glossdef>
</glossentry>
</glossgroup>- Task topics cover how-to procedures.
<!-- Task topic -->
<task id="publish-dita-output">
<title>How to Publish DITA Content</title>
<taskbody>
<steps><step><cmd>Open your DITA map in the editor.</cmd></step></steps>
</taskbody>
</task>- Reference topics link different elements within the system and may include data for supporting tasks, for instance, by providing equipment and product specifications.
<!-- Reference topic -->
<reference id="dita-output-formats">
<title>Supported Output Formats</title>
<refbody>
<table>
<tgroup cols="2">
<thead>
<row>
<entry>Format</entry>
<entry>Use Case</entry>
</row>
</thead>
<tbody>
<row>
<entry>PDF</entry>
<entry>Print-ready documentation</entry>
</row>
<row>
<entry>HTML5</entry>
<entry>Web-based help portals</entry>
</row>
</tbody>
</tgroup>
</table>
</refbody>
</reference>- 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.
<!-- Concept topic -->
<concept id="what-is-dita">
<title>What Is DITA?</title>
<conbody><p>DITA is an XML-based open standard...</p></conbody>
</concept>Each topic is saved as a separate .dita file, a standard DITA file format readable by any DITA-compatible editor. A DITA map (.ditamap) then assembles individual topics into a complete publication, defining their order and hierarchy without duplicating content.
<!-- DITA map -->
<map>
<title>User Guide</title>
<topicref href="intro.dita"/>
<topicref href="tasks.dita"/>
</map>Topics are 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 documentation 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 XML 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 content management 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 DITA writing enables technical writers to build on top of existing files instead of writing from scratch.
Thereby, the inheritance principle facilitates reusability and traceability within the system.
Extensive reusability
The DITA content model 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
Conref (content reference) and keyref (key reference) are core DITA XML examples of reusable elements that allow authors to maintain a single source of truth across dozens of documents. These capabilities 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 XML enables publishing in different output formats, such as PDF, HTML, Web Help, XHTML, EPUB, and more.
Even when used in 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 simplify search 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
Poised to start your DITA project?
Book a free consultationChallenges you may face when adopting DITA
Switching to a structured DITA technical writing 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. Still, a successful DITA adoption depends on choosing the right authoring approach and employees understanding how to use DITA within their specific workflow. So business leaders should consider investing in staff 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 XML has been an up-for-grabs open standard, offering a DITA writing methodology that any organization can adopt. 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). Either path lets technical writers move from unstructured documents to a structured, reusable, single-source workflow.
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 XML for technical writers 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
I’d 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 – but each vendor tries to take its basic capabilities to the next level and extend DITA standards’ competitive features. 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.
DITAworks Webtop is Instinctools’ DITA-based platform for enterprise structured content management, supporting authoring, review, translation, and multi-format publishing of technical documentation.
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.
How has DITAworks adoption influenced document creation time and translation costs?
Read the case studyBear 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.
Level up documentation management with our support
Let’s talkFAQ
Darwin information typing architecture (DITA) is an XML-based standard to create, edit, manage, and publish large volumes of documentation in multiple formats and languages. The DITA XML standard’s core principles make it stand out from the line of other content management solutions. Thanks to the modular structure, inheritance principle, components’ reusability, and extensive traceability across the system, DITA XML is a top pick for enterprises with a sophisticated content structure.
DITA stands for Darwin Information Typing Architecture – an open XML-based standard developed by IBM in 2001 and standardized by OASIS. It defines a framework for authoring, managing, and publishing modular technical content.
DITA-powered software can cover all documentation-related processes, from authoring and editing to reviewing, publishing, and managing available content. Initially, it was created to deal with technical documentation, such as user manuals and manufacturing instructions. Later, the standard extended beyond this narrow area and gained popularity for structured management of training materials, marketing documents, etc.
Both concepts are central to structured authoring, but they operate at different levels. XML is a general-purpose markup language for storing data in structured files. DITA XML is a specialized architecture that defines how those files are organized, typed, and reused. When comparing DITA vs. XML, think of XML as the language and DITA as the methodology built on top of it. You can use XML on its own for structured data, but to scale structured authoring across large documentation sets, you need a system like DITA to enforce consistency and enable reuse.
DITA-driven software has one or several DITA processors for authoring and publishing modular content. DITA Open Toolkit and DITA XMLmind are examples of the wide-spread options. Both processors are open-source and can be freely used to craft your custom DITA-based tool.
