Headless content management is a great option for all kinds of publishers, including those that produce technical content. Many technical writers aren’t knowledgeable about the benefits of headless. This post will look at how headless measures up against legacy technical content practices in 11 key areas.
Published on Aug 13, 2020
For a couple of decades now, some organizations have developed their technical documentation using an approach called DITA—the Darwin Information Typing Architecture. As implied by the name “Darwin”, this approach was supposed to evolve to address future content requirements. But in practice, DITA has become a badly dated approach to managing content that promises capabilities it can’t deliver satisfactorily. According to a DITA satisfaction survey, “62% of respondents using DITA are—to varying degrees—dissatisfied.” A growing number of organizations that use DITA are exploring alternatives, and those that decided to try DITA often quickly regret their decision.
DITA advocates often state or imply they offer the only way to manage structured content. They rarely acknowledge there’s an increasingly popular alternative to DITA: headless content management. In some cases, these writers aren’t familiar with headless yet, and therefore don’t know that it is an option. While DITA and headless both structure content and support content consistency, reuse and customization, the similarities end there. Headless is a modern approach to content management. DITA is a dated one.
DITA was designed for technical documentation. Despite fitful efforts to tweak the standard to broaden its appeal, DITA remains anchored to specific conventions associated with technical documentation. DITA hasn’t enjoyed wide success as an approach to manage marketing content, general interest interactive websites, or popular smartphone apps. DITA is about “specialization” for a specific purpose: tech docs. The mainstreaming of DITA outside of this narrow focus has been discussed for many years but has never actually happened because the core architecture of DITA isn’t viable as an enterprise-wide solution. DITA content tends to live apart from the rest of the enterpriseʼs content.
Headless is suitable for any kind of content. Although headless is widely used for technical documentation, it can do much more. It powers all kinds of websites: from e-commerce sites to major global newspapers. It’s the approach of choice for smartphone apps. It drives many of the world’s favorite online games. And it’s the go-to content approach for emerging applications such as augmented reality and the internet of things (IoT). Because of the versatility of the headless approach, it can be used by enterprises to manage all their content.
DITA is based on a dated paradigm for structuring information. It recreates a textbook-like structure, breaking information into three basic types: tasks, concepts, and references (glossary entries and troubleshooting are also options). These document-centric ideas reflect the prevailing views of the 1990s (when DITA was conceived) of how people need to learn and navigate through information while reading thick user manuals. Readers are expected to conform to the structure of the information. DITA was formalized before the explosion of user research in the new millennium and the development of UX best practices.
In contrast to DITA’s didactic approach, headless embraces an outward-facing stance that is focused on the reader’s needs. Because headless is premised on delivering specific and targeted information through APIs, the needs of audiences decide how the information is structured. The content structure can be modified based on audience feedback.
A common misconception is that DITA content is portable because DITA is a standard. Yet being DITA compliant doesn’t mean that your content is interoperable with another publisher’s content. DITA is a vendor standard that allows you to migrate your DITA content from one tool to another. The standard is necessary because the description of the content structure itself is closed. That structure is wrapped up in a “tree,” meaning that elements within DITA content aren’t known to or accessible by outside parties. The publisher, who controls the filtering of content elements within the tree, is a gatekeeper. This way of structuring has significant practical drawbacks. It’s difficult or even impossible to merge content from different sources because each will describe their content in different ways.
With headless, the content is open (API-accessible), so a vendor-agreed standard isn’t needed. Organizations routinely move content between headless systems without difficulty. Headless is designed to let you merge and combine content from different sources. It allows organizations to share libraries of content with outside parties or share only select fragments of content. Organizations can share whatever they want to easily, and they can pull in content from elsewhere without difficulty as well.
DITA often claims to be “semantic,” another misleading characterization. Despite its complexity, the DITA framework is too generic to align content coming from different sources. Two different sources won’t agree on what their models mean because there will invariably be idiosyncratic differences in how each publisher decides to implement the DITA framework. In DITA, meaning is influenced by the nesting of elements inside one another. The meaning of an element depends on its position on the DITA tree—not unlike a site map for a website. What the content structure means is locked in each organization’s specific implementation.
The structure of content in headless promotes greater autonomy, focusing on relational linking rather than deep nesting. With headless, the meaning of elements is independent of their location in the larger content model. Other parties don’t need to understand the entire model to be able to access an element. Each element has a unique API address that can be accessed directly without worrying about its position in a tree.
DITA is multiformat rather than omnichannel. It lets you create documents in different formats: web, print, PDF, or CD-ROM. DITA relies on templates to format the content for a specific destination. But producing different formats by itself doesn’t support an omnichannel experience. Users don’t simply want different versions of the same content; they need the content elements, the channel, and the experience to come together seamlessly in real-time so that it adapts to the user’s context, something DITA can’t manage.
Headless is channel-agnostic by design. A headless system doesn’t have the limitations that result from templates: it is not restricted to a set range of predefined outputs. It can connect to a multitude of libraries that can assemble and present the content in limitless ways, which means it can be readily delivered to any channel or platform. Moreover, it is simple to switch out libraries so that the content can be repurposed easily. Headless supports customers as they switch between channels and as they expect different experiences and content when doing so.
The basic structure of DITA was set in place in the early 2000s by IBM. DITA has had a few minor revisions since then, but the core standard hasn’t changed much, and doesn’t seem likely to. DITA is managed by a voluntary committee of mostly small size consultants and vendors with limited participation by large enterprises. Most recent activities have focused on how to simplify DITA to broaden its appeal—a recognition that the standard has become unwieldy and unpopular. Significantly, the one proposal to reform DITA that might have extended its popularity—adding JSON compatibility—was dropped due to a lack of interest by committee participants. Without JSON compatibility—the basic foundation of modern content exchange—DITA is isolated in its narrow niche.
Headless, in contrast, is evolving rapidly as an approach to managing structured content. Enterprises can choose among dozens of headless vendors, and industry growth has been explosive. Headless is being adopted by firms of all sizes and in all industry sectors, including a significant portion of Global 500 enterprises. And the capabilities available to manage headless content keep expanding as well, with new API capabilities and a growing range of microservices available to enable integration with other systems and data sources.
Structuring your content is of little value if you can’t easily change the structure when necessary. When it comes to the ability to change, DITA is fragile, while headless is agile.
DITA mixes together content structuring and content logic (referred to as “grammar,” “profiling,” etc.) into a single package. Every element of content is a branch, sometimes many levels deep, of an ornate XML tree. The tree can be complex when first created, and it can become an even bigger challenge to manage if you need to add or delete branches from it later on. DITA is hard to change once it’s in place. And the XML grammar used to transverse the tree to locate specific items doesn’t fail gracefully when it encounters the unexpected. Writers confront cheerless tasks such as debugging missing references and troubleshooting validation errors.
Headless avoids this commingling. It keeps the structure of the content separate from the code used by other applications and systems to query and assemble the content. This allows changes to the structure of the content straightforward to make because they are not dependent on nested internal logic. The architecture of headless systems is designed so that the content structure can add or remove specific features as needed.
DITA is notorious for being difficult to learn and for requiring extensive training. DITA expertise can entail years of practice to understand its inner logic and coding conventions. One major learning barrier is that the content structure depends on the markup that’s nested within the content, where even simple sentences can be embedded with coding qualifications. Few writers want to deal with the intricacies of nested XML markup, and many employees rebel when they are forced to adopt DITA and encounter its steep learning curve. Disguising DITA’s markup behind a slick UI doesn’t eliminate its conceptual hurdles and implementation challenges. For DITA to work, authors have to get involved in the code to some degree—and sometimes they’ll need to become XML developers. Employees who can deal with both writing and code development are expensive and hard to find. That’s a major reason DITA doesn’t scale across the enterprise: few people have the specialized skills required to work with DITA.
A good enterprise-oriented headless CMS such as Kontent.ai has a simple authoring interface that’s designed with non-technical users in mind. It divides content into parts so that authors can readily focus on the part they need to write, edit, or comment on. A good authoring system won’t make writers use distracting and cryptic markup in their text. It’s worth noting that headless CMSs do vary considerably in their authoring experiences. While almost any headless system will be easier for authors to use than DITA, not all headless systems offer a good user experience, especially ones that are Git-based (rather than Cloud-based) and rely on Markdown. So be sure to evaluate the authoring experience carefully.
DITA is a Web 1.0 technology, designed to deliver static content. It relies on a template to format the entire body of content every time even a small change is made. DITA content is compiled: all of the material needs to be assembled together at the same time. Because elements that are needed are a subset of a much larger tree, the time required to filter the tree for desired elements and compile them together is plodding by modern standards.
Headless is a content architecture for Web 3.0 and beyond. It’s ready for the distributed—and automated—discovery, retrieval, and transformation of any kind of content. It can deliver precisely what is needed, when it is needed. It can process requests for information and transmit changes in the information instantly. Because it can be integrated into real-time AI services, headless content can be changed, converted, and reshaped. For example, images can be processed through APIs to change their framing, coloration, or other properties on the fly.
Because it is a documentation approach, DITA isn’t designed for dynamic content that needs to change based on user behaviors or context—something that customers increasingly expect. Instead, DITA is designed to output predefined packages of content. It’s a bad approach if you ever need to tailor content to address fluid situations or highly targeted requests for information. You need to plan every possible contingency and produce multiple versions to address each contingency. Even then, you can’t be sure you’ve planned for everything. Your result will be off-target.
Headless content can refresh continuously. It is dynamic and granular: the details users receive can be specific to their context. For example, headless is being used in IoT applications to present content based on a person’s presence in a location: their gestures, movements, and proximity to other people and things.
DITA imposes a rigid framework on how content is structured. Enterprises need to use a wide range of content structures. But they need to shoehorn their diverse range of content into a limited number of recognized information types, which may not be appropriate for their needs. Otherwise, they face the onerous burden of developing custom information types within DITA’s intricate document typing definition system. Many enterprises discover that the coverage of DITA’s default information types is inadequate for many kinds of enterprise content that’s not technical documentation. Yet the hassles of custom development of information types in DITA are too high.
Headless takes a different approach. Instead of imposing a standard, it is based on an open architecture. Different publishers can decide for themselves how they want to structure their content so that it is customized to their needs. And the development of content types is simple compared to the DITA approach.
Many years ago, the content strategist Sara Wachter-Boettcher discussed the need to make content future-ready in a widely read A List Apart article. She cited the experience of National Public Radio (NPR)—an early adopter of headless content management – as an instructive example of how to make content ready for the future. She noted: “Technical communicators have been pushing DITA (Darwin Information Typing Architecture) for years—and there’s nothing particularly futuristic about it... Many technical communicators insist DITA should be the web’s standard structuring approach, but it’s never quite caught on. It’s also not the only way to do it.”
Today, headless content management has moved into the mainstream. It offers the most viable approach to managing structured content. Both writers and developers appreciate how headless lets them focus on their respective responsibilities. No matter what kind of content you work with, headless can make it more manageable.
What if we told you there was a way to make your website a place that will always be relevant, no matter the season or the year? Two words—evergreen content. What does evergreen mean in marketing, and how do you make evergreen content? Let’s dive into it.
Lucie Simonova
Aug 29, 2022
How can you create a cohesive experience for customers no matter what channel they’re on or what device they’re using? The answer is going omnichannel.
Zaneta Styblova
Mar 10, 2022
In today’s world of content, writing like Shakespeare is not enough. The truth is, there are tons of exceptional writers out there. So what will make you stand out from the sea of articles posted every day? A proper blog post structure.
Lucie Simonova
Jul 22, 2022