Beyond DITA vs. DocBook: Prioritize Your Business

I’ve recorded a short video above to voice my thoughts and then written this companion piece to continue the discussion in more detail.

Recently, the tech content landscape seems abuzz with discussions about “DITA vs. DocBook”. One might anticipate that I’d join this debate, championing one over the other. But that’s not the story today. Like parents passionately arguing over parenting styles when their focus should be their child’s well-being, our focus should be the health and success of your business, which deserves a comprehensive, multi-faceted approach.

Consider these questions:

• How streamlined is authoring and managing structured content in our system?
• Does our approach facilitate collaboration without intricate training or technical barriers?
• Is publishing to multiple channels a seamless process or a cumbersome chore?
• Are we chained by a complex tech stack that makes pivoting or adapting a Herculean task?
• Is our content strategy truly aligned with the bigger picture—the business goals?
• And, crucially, how does the end customer perceive and interact with our content?

If these resonate more than the XML debate, you’re beginning to see the broader spectrum.

A myopic focus on XML standards can lead to several pitfalls. Throughout my years of experience in the tech industry, I have had the opportunity to witness and hear stories from numerous companies that have grappled with this very issue.

• Unsatisfying Authoring Experience: An intuitive authoring experience is non-negotiable. A system resembling a coding platform, rather than an authoring one, can deter contributors and stifle creativity. For example, one company I spoke with had attempted structured authoring using a non-structured platform. The convoluted syntax and code-like markup frustrated non-technical writers. Publishing often broke. Yet another company I came across tried forcing authors into rigid DITA structures ill-suited to their content. Authors struggled to contort their writing style to fit arbitrary structures.

• Overlooking the Best Way to Write: Content shouldn’t be force-fitted to adhere to a standard. The narrative and requirements should drive the technical approach. Mandating DITA for all technical documentation led one firm I encountered to reshape their writing to fit DITA models rather than choosing the optimal format for their content goals and audience needs. They became so engrossed in the intricacies of XML standards that they lost sight of the bigger picture.

• Stifling Collaboration: Modern content creation thrives on collective effort. Bottlenecks from debates over XML specifics can derail this synergy. At an organization I visited with a homegrown CCMS, every minor XML change required developer intervention, killing collaboration momentum. Another company relied on isolated content silos, where they often wrote the same ideas multiple times when the content could have simply been reused. Authors wasted hours piecing together related information.

• Compromising End User Experience: Technical precision, while commendable, is secondary to relevance and resonance with the audience. Focusing heavily on structured authoring consistency at the expense of optimizing end user experience leads to pristine but inaccessible content. For instance, there was another case where a company had perfectly structured and validated content that was painful for customers to navigate, so they couldn’t find the answers to their questions. A lot of effort went into writing content that was not being consumed.

• Hindering Business Outcomes: Content strategies must align with business objectives. A disconnect leads to inefficiencies and lost opportunities. Many companies align their technical documentation strategy tightly to business goals, leading to wasted efforts. Another concern is that poor content discovery can cost companies millions in missed website conversions.

• Inhibiting Innovation: If you are continually trying to catch your tail, you’re wasting valuable time achieving very little. A robust foundation enables innovation. If a company is too focused on addressing foundational challenges, forward momentum stalls. Companies with inflexible content systems are slower at launching customer-focused content initiatives and new self-service support channels.

Visualize content strategy as two parallel tracks running alongside each other. On one side, we have the technical documentation requirements, which form the building blocks, starting from the foundational XML standard and ascending upwards. On the opposite track, we have the solution and overarching strategy, which begins from the summit of business impact and drills downwards, informing each layer below. While these paths might seem distinct, they’re deeply interwoven, each influencing and shaping the other. As we delve into these layers, remember that we’re constantly moving between these two tracks, ensuring our technical decisions are always aligned with our strategic goals.

• The XML Standard Used: Beyond just a foundational choice, XML standards like DocBook or DITA underpin structured authoring. This methodology ensures consistency, promotes content reuse, enables efficient translation, and supports multichannel publishing. However, if not implemented well, it can lead to an unsatisfying authoring experience where writers feel they are coding rather than crafting content. The aim should always be a balance between adhering to the standard and ensuring ease of content creation.

• Authoring Product Dynamics: This is where the rubber meets the road for structured authoring. The tools should allow authors to focus on creating content, not wrestling with the underlying technology. The product should be intuitive, hiding the complexities of XML, thus preventing situations where too much time is spent managing content, causing the quality of writing to take a hit.

• Collaboration: Modern technical documentation isn’t crafted in isolation. It’s the combined effort of writers, developers, support teams, and more. It’s vital to have systems in place that facilitate smooth collaboration. Otherwise, the synergy that’s required to produce stellar content is lost, leading to roadblocks and inefficiencies.

• End-User Customer Experience: – Beyond the words on the page, it’s about optimizing content delivery. Which channels best serve the content? How intuitive is the design? How effective is the search functionality? Is the content timely and up-to-date? A focus solely on structured authoring without considering these aspects can compromise the end-user experience.

• Business Impact – The Strategy: The culmination of our efforts. It’s here we measure the ROI. Are our content strategies driving more conversions? Reducing support calls? Enhancing user satisfaction? The answers to these questions determine the success of our approach. It’s not just about crafting content; it’s about ensuring that content aligns with and drives business objectives.

Having traversed the intricate web of technical content, we realize that our narrative should encompass more than just XML standards. The questions we posed at the outset—about streamlined authoring, collaboration, publishing, adaptability, alignment with business goals, and end-user perception—are all addressed in the layers we discussed. It’s not a matter of pitting one XML against another but of crafting a strategy that holistically caters to all these facets.

Our goal isn’t to dive into a granular debate but to elevate the discourse. Much like nurturing a child, our focus should be on the overall health and success of our business. Every decision, every strategy, and every piece of content should be a step towards that overarching goal.

In this vast realm of technical documentation and content, let’s champion a vision that’s comprehensive, ensuring the prosperity of our businesses takes center stage. The conversation should revolve around building content strategies that empower our enterprises to thrive and evolve in an ever-changing landscape, rather than arguing about which standards are best. It is in this approach that we find the path to true success, where our content not only reflects our brand but also actively contributes to its growth and vitality.