Whether we are talking about technology, governments, business, culture, or the environment – we live in a world of constant change. In our field of work, many of us see changes impact our documentation on a weekly, if not daily, basis. To keep pace with these changes and maximize content reuse, it has become standard practice to employ some form of topic-based authoring tool.
However, when technical communication professionals consider their content authoring and management strategies, the best solution is not always clear. Does it require a component content management system (CCMS) based on the Darwin Information Type Architecture (DITA)? Or will a more general solution for topic-based authoring provide the necessary features?
The answer is: It depends.
There is no question that DITA provides the gold standard for breaking content into reusable pieces or “components”. However, authoring and content management solutions are a bit like automobiles.
A Ferrari is an ideal car for a Formula 1 race, but it requires specialized fuel as well as a highly skilled driver and supporting pit crew. Meanwhile, a Renault hybrid sport utility vehicle (SUV) is a general-purpose auto useful for regularly transporting family members to work, school, and other locations; it is fuel-efficient and can easily be used by the average driver. Yet, unlike these automobile examples, many technical documentation requirements fall somewhere in between the two extremes.
This article examines five questions that technical communication professionals should ask themselves to help determine whether a DITA CCMS or general topic-based authoring solution will provide a better fit for their needs. Before diving into those questions, however, let’s quickly review some of the basic differences in how DITA and general topic-based authoring systems handle content.
The difference is in the structure
Both DITA CCMS and general topic-based authoring products help technical communication professionals to create and manage reusable content while ensuring consistency, reducing redundancy, and streamlining content production workflows. However, the two systems differ in their approaches.
Perhaps the biggest difference is how content is structured. A topic-based authoring system enables a writer to structure content as topics, which can be of any length. A DITA CCMS enforces the creation of small, standardized content components, and it will automatically prohibit an author from exceeding pre-determined boundaries.
It might sound paradoxical, but the strict component boundaries maintained by a DITA CCMS provide greater flexibility when it comes to content reuse, since the structure results in many more components that can be mixed and matched to update or create new documentation. Using a DITA CCMS to enforce the creation of small, well-defined content components can also make it easier to train Artificial Intelligence engines and chatbots, as well as using Natural Language Processing and Machine Learning for precise insights and personalized content delivery. Additionally, a DITA CCMS allows semantic tags to be added to content components, which significantly facilitates the traceability and auditability required to demonstrate compliance with government and industry mandates.
By contrast, technical communication teams that use a general topic-based authoring solution have the flexibility to create topics up front, which may range from a few sentences to multiple paragraphs. There may be a limited ability to drop longer topics into new documents “as-is”. However, features in topic-based authoring solutions, such as snippets and conditional text, can be used to create variants of topics and facilitate/automate updates through reuse mechanisms. Today, well-designed content created with general topic-based authoring solutions is applied to AI, chatbots, and compliance auditing and traceability, but there is more room for variability.
These are just a few of the distinctions between a DITA CCMS and a general topic-based authoring solution, but they are the ones that most often come into play when considering which offering is the better fit for a given organization.
Five questions to consider
Now let’s review the five questions technical communication professionals should ask when evaluating their content authoring needs.
1. How complex is the documented product, service, or process?
Complexity is a primary consideration when selecting a DITA CCMS or general topic-based authoring solution. At one end of the spectrum are complex physical products such as advanced medical devices, automobiles, and factory machinery, to name just a few. Such products may be available in multiple configurations and, in some cases, be supported by a range of accessories. The complexity is further multiplied by the fact that companies usually need to maintain documentation for multiple product releases or models. For example, Boeing announced the rollout of its 777X in 2023, but older 777 models have been in service since 1995. Products that carry this level of complexity are particularly well-suited for a DITA CCMS.
Meanwhile, software is an example of something that falls somewhere in the middle. While applications are complex, new version releases usually enhance or add features to existing functionality. Additionally, software platforms may contain functionality that is shared across applications. If these applications are used to automatically run equipment, for example, network systems, there may be a need for granular content components. Otherwise, the nature of shared functionality in an application or software platform can, in many cases, be readily supported by a general topic-based authoring solution.
At the other end of the spectrum are simpler products, such as bicycles and electric fans. This category also includes an organization’s documented policies and processes. Some real-world examples include pilot pre-flight checklists, customer support escalation procedures, employee benefits, and facility evacuation procedures – cases where changes are relatively infrequent. These scenarios are well served by a general topic-based authoring solution.
2. What is the scale of the content being created?
Complexity is one dimension; another is scale. For the purposes of this discussion, scale refers to two elements: The first is the amount of documentation and the number of elements it contains, including multimedia. Sometimes this involves terabytes of information. The second element is the number of people involved in the creation of content, including technical communication professionals, subject-matter experts (SMEs), and other contributors and reviewers. Some global companies have hundreds or thousands of employees who, while belonging to different business units, are responsible for anywhere from dozens to hundreds of complementary or related product lines.
Technically, either a DITA CCMS or one of the more modern technical authoring solutions can be used to support large-scale requirements. However, the smaller, componentized topics dictated by a DITA CCMS can expedite searches through large volumes of data, as the process is closer to a standard database search instead of sifting through paragraphs. Additionally, these components featuring very small, specific pieces of information can facilitate content reuse across a wide range of projects and users.
3. Does the documentation cover highly regulated products or services?
Certain industries face a higher level of industry and government oversight, not only for the products or services they deliver, but also for any supporting documentation. Chief among these are medical devices, pharmaceuticals, food and beverages, automotive, aerospace and aviation, to name a few. For many organizations delivering solutions in these markets, the ability to facilitate compliance is a compelling reason to adopt a DITA CCMS.
DITA supports the ability to organize reusable content with consistent tagging for accurate tracking and auditing. This functionality, combined with the enforcement of topics as small components, significantly simplifies the ability to pinpoint changes in the document in order to demonstrate compliance. The granular views and ability to review previous versions make it easier to conduct any impact or regression analysis.
I experienced the strength of DITA for compliance first-hand while working for several years as a technical writer for a global producer of medical devices. For example, if we had to replace a defective part of a computed tomography (CT) imaging system with a new part, there would be a unique tracking number for the defect. So, using our DITA system, we would add this tracking number to every related topic in the documentation, which made it easy to show the auditor that we only made this change related to the defect. Similarly, when the medical device company changed a requirement from 2 nanometers to 5 nanometers, we had to document this change and submit that documentation to the United States Food and Drug Administration (FDA). Here again, using DITA, it was easy to document the changes. These are just two of the many ways in which DITA-based documentation can make regulatory audits a much smoother process.
4. How important is structural consistency across the organization and/or supply chain?
Usability studies have shown that presenting information consistently improves reader comprehension. For this reason, when a company offers multiple related products, ensuring a consistent documentation experience is critical – whether the person viewing the content is a customer, partner, or member of the company’s service and support team. The look, navigation, and any shared data points should be the same. This consistency also needs to extend to customers, systems integrators, or other business partners that deliver the company’s solution or service under their own brand.
The most effective and efficient way to ensure documentation consistency across a company’s own business groups and third parties is by using a DITA CCMS to help enforce this consistency. Alternatively, an organization with a general topic-based authoring solution can designate a centralized technical writing team to produce documentation for these different constituencies. However, depending on the frequency of updates, this approach may create bottlenecks within the company.
5. What resources are available to use and maintain the authoring solution?
When evaluating content authoring options, organizations need to consider their available resources. What access to funding and Information Technology (IT) support is available to implement and maintain the solution? And what expertise does the technical communication team have?
A DITA CCMS will require technical communication professionals to have DITA-specific training. If the organization does not already employ DITA-aware writers, it will need to train staff or hire at least one expert. Additionally, while a DITA CCMS includes robust content management, it will often need to be integrated with a third-party content delivery portal to publish documentation in a range of web, mobile and print formats – requiring IT resources and expenditures. The alternative is to have an XML expert well versed in the DITA Open Toolkit (DITA-OT) and/or XSLT and XSL-FO to build publication output configurations.
On the other hand, most technical communication professionals have the required knowledge to get up and running quickly with a general topic-based authoring solution and, in many cases, the functionality for publishing content in multiple formats is embedded in the solution. Moreover, there is now an industry move to embed topic-based authoring software in cloud-based content management systems for an all-in-one solution.
Meeting your authoring match
With comparatively few exceptions – such as when there are extensive compliance demands – there is no one factor that will definitively point to a DITA CCMS versus a general-purpose topic-based authoring system. Instead, the combined answers, and how each answer is weighed against an organization’s specific priorities, should help technical communication professionals to lean toward one solution or the other.
There are two other factors to consider: First, within large corporations, the best option for some business units or departments may not be the optimal choice for others. I have come across examples where different groups within the same company have either a DITA CCMS or a general-purpose topic-based authoring system in place, depending on their needs. Second, your answer to the questions above will only capture a moment in time. Some of the small or mid-size, high-growth companies that are well served by general-purpose topic-based authoring solutions today will see the need to migrate to a highly structured DITA CCMS in the future.
Technical communication professionals not ready to make the DITA leap can hedge their bets by using their general-purpose topic-based authoring solution to implement DITA-like best practices. For example, create small topics that can be more readily reused, leverage templates and Cascading Style Sheets (CSS) to ensure consistency, and utilize version control to provide a mechanism both for managing approvals and providing a level of traceability. Finally, investing in DITA training can provide additional ideas on how to incorporate established DITA practices using an existing topic-based authoring solution.
We live in a world of constant and rapid change. Within the technical communication community, the ability to maximize content reuse has become critical to keeping pace. Both DITA CCMS and general topic-based authoring products provide powerful solutions for creating and managing reusable content while helping to ensure consistency, reduce redundancy, and streamline content production workflows. By addressing the five questions reviewed in this article, technical communication professionals can determine which technology approach is best for their organization today and prepare for their future needs.