XML vs. Docs as Code: Breaking Down Structure and Flexibility in Technical Writing

Technical writing has always struggled between controlling and delivering. On one hand, highly structured XML-based formats promise to manage content from creation to publication.

On the other hand, lightweight formats offer developers the flexibility to create documents quickly.

As technical teams decide which framework to use for documentation, there is no one right choice.

This article compares philosophies to understand the tools for each use case, from structured authoring to flexible collaboration.

What is XML documentation?

XML provides a robust standard for creating structured documents. Semantic markup and metadata efficiently manage content across enterprise publications scale.

It helps to capture complex documentation using descriptive, nested elements like <title>, <table>, <warning>, <prereq>, etc.

The writer defines data models that include DocTypes, custom XML tags, attributes, and namespaces optimised for deliverables.

Style sheets transform XML into different formats, while standard schemas enable interoperability.

It has technical features for supporting complex authoring scenarios like:

• Self-contained objects

• Extensibility

• Validation through DTDs or XML Schema

• Entity references for reuse

• XSLT functionality for separation of data from presentation.

The example below illustrates how semantic structures separate properties from content.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="analytics_module">
  <title>Analytics Module</title>
  <shortdesc>The Analytics Module provides APIs for generating usage reports and statistics for the platform.</shortdesc>
  <conbody>
    <section>
      <title>Overview</title>
      <p>The Analytics Module is a server-side component that integrates with the core app to 
        capture events and user actions. It offers a reporting dashboard and developer APIs.</p>
    </section>
    <section>
      <title>Architecture</title>
      <p>The module has a pluggable provider model that supports different storage backends like 
        MongoDB, Redis, etc. Default implementation uses time-series optimized ClickHouse DB.</p>
      <p>Pre-aggregated metric events are published by apps to Kafka queue consumed by the 
        Analytics module for storage and processing.</p>
    </section>
  </conbody>
</concept>

Key aspects that XML facilitates are:

• Schema-based structure

• Validation rules

• Granular semantics

• Format independence

• Single source, many outputs

• Industry-standard integrations

• Extensibility of data models.

XML has led to several adopted documentation standards for technical publications. Some of the most common standards and frameworks include:

• DITA

• S1000D

• DocBook

• XHTML

• EPUB.

These standards structure the content for machine readability and provide a normalised way of feeding content across systems, platforms and archives.

Separating the structured XML core from the stylesheets provides flexibility. These are examples of some output formats:

• Web for casual reading

• PDF for remote fieldwork

• Specialised browser-based for interactive product experiences

• E-book formats for mobile consumption.

Due to its complexity, XML documentation tools have a significant learning curve and only make sense where certain scale and consistency requirements exist.

Factors that tend to justify the use of XML technical writing include:

✔ Enterprise documentation with thousands of interlinked product specifications.

✔ Manuals distributed over decades that need backwards compatibility.

✔ Regulated content that demands strict process control.

✔ Publications that have to be output in many formats for different contexts.

Use XML documentation when the need for control, compliance and multi-channel content distribution outweighs the cost of implementing the platform.

For smaller help sites, the return on investment may not justify the effort required.

Introducing docs as code

Docs as Code handles documentation like software code. Developers and tech writers can work together on docs using familiar code management tools and workflows.

For example, the documentation can now be stored in Git instead of a separate CMS.

Instead of isolated delivery, it facilitates continuous integration with constant feedback.

It is possible to combine automation around builds and testing. Following agile principles enables continuous delivery that matches the frequency of software changes.

Docs as Code uses a simplified and concise text-based format such as Markdown for writing before conversion for delivery.

# Docs as Code

## Introduction

Text can be easily formatted into **bold**, `code snippets`, [links](https://example.com), and lists using simple Markdown syntax.

Lightweight markup formats use simple text-based syntax. This involves adding formatting, links, images and more to plain text and converting it into a complete web page or document.

Finally, it is also possible to use static site generators such as Jekyll, Hugo, Docusaurus, Gatsby or MkDocs to write in Markdown. These generators provide templates, themes and helpers to output a complete static website.

Small teams can create decentralized documentation by combining Git version control with headless CMS. This approach is more flexible than XML alternatives.

The docs-as-code approach works best when teams need to collaborate in a decentralized way. Ideal for early development and content that needs to get changed and delivered fast.

Explore the 6 key differences

We will compare six key aspects of XML and doc-as-code to determine the best option for each need.

1. Authoring complexity of XML vs simplicity of Markdown

   • Using nested semantic markup in XML enables reusability but requires a significant learning curve.

   • Lightweight markup languages allow you to easily create content using simple text markup. Yet they lack reuse mechanisms, making it challenging to maintain consistency across topics.

2. Heavy structure vs flexible lightweight docs

   • The rigorously defined structure of XML ensures consistency but often limits agility.

   • Lightweight markup provides flexibility for customised architectures but risks inconsistencies without validation safeguards.

3. Multi-step publishing vs continuous delivery

   • XML's process is multi-stage and requires finalizing content before applying complex transformations.

   • Lightweight documents use a continuous software approach for constant integration and delivery. Recently, some modern CCMS platforms have begun to bridge this gap.

4. Specialised skill sets vs open contribution

   • Mastering the complexities of XML standards such as DITA requires intensive specialisation.

   • Using simpler syntax in lightweight documents can make it easier for contributors to take part. Sophisticated implementations still need web technology skills, such as CSS, static page generators, or DevOps.

5. Legacy tools vs modern stacks

   • XML often requires licensed, proprietary CCMS tools and desktop editors.

   • In contrast, doc-as-code documentation allows free, open-source, modern web stacks. Online automation services support cloud collaboration, distributed Git workflows, and continuous integration.

6. Challenges of content reuse and portability

   • Although the latest players are closing the content reuse gap, the strengths of XML make the modular portability of content across systems a key advantage over fragmented lightweight markup formats.

   • Docs-as-code allows for the progressive adoption of technology, enabling it to take advantage of emerging state-of-the-art techniques.

Next steps for advancing technical writing

XML documentation will continue to play a vital role in the technical communication stack. Due to its unique strengths in content reuse, CCMS integration, multi-channel publishing, and standards compliance.

Consider XML documentation for large, complex and structured content with multi-format publishing requirements. Useful for long-term projects with standardized deliverables or compliance requirements.

Docs-as-code enables faster time-to-market, collaborative workflows and modern technology stacks. This aligns with iterative documentation for early-stage applications, where consistency can gradually improve.

Wrapping Up

This article highlights that technical writers and developers should adapt their approach to the type of content. When evaluating documentation systems a hybrid strategy often works best.

Docs-as-code is a versatile tool, but it cannot yet replace XML for large-scale consistency and control-critical publishing. Both philosophies must evolve to meet different content needs with complementary strengths.

Happy New Year, everyone!