DITA vs Markdown: Reuse, Benchmark, and the Decision Threshold

A Medium case study follows a technical writer who learned Markdown, VS Code basics, terminal navigation, Git commands, branching/merging, and pull-request workflows in 4 days. That 4-day ramp is the real docs-as-code advantage. It also explains why the 30% faster builds and 25% fewer-error numbers in the DITA-vs-Markdown debate are so often misunderstood: they only appear above a reuse threshold that most Markdown teams never measure.

Below that threshold, Markdown's plain-text familiarity and single-commit rebuild are enough. Above it, documentation work becomes copy-paste maintenance: updating Word files, PDFs, screenshots, and previously shared versions by hand instead of changing a source file. The hard benchmark for that duplication is $880,250.

DITA was designed to enforce structure and reuse from day one; Markdown was designed as a text-to-HTML convenience for web writers. The choice is not XML against Markdown. It is reuse against copy-paste, and the threshold is measurable. Benchmark it before choosing.

The Reuse Lever

Copy-paste is the silent tax on every Markdown-based documentation set that crosses the topic-count threshold. The mechanism is deceptively simple: a version number changes, an editor runs grep-and-replace across many `.md` files, and the static-site generator invalidates every cached HTML page that contained the old string. Docusaurus and Hugo then re-render the full site and re-run link checks, not because the content changed, but because the build system cannot know which pages are actually affected. The DITA answer to this is not a style preference — it is a structural difference in how content is stored and addressed.

DITA stores each fact once in a `.dita` topic. The `conref` and `keyref` mechanisms insert that topic or element into multiple DITA maps, so a single edit propagates to every output at build time. There is no second copy to drift. This is the core of the reuse lever: the unit of authorship is the topic, not the page, and the unit of reuse is the reference, not the paste. When a version number changes in a DITA source, you edit one file, and every map that references it picks up the change when the transform runs. The Markdown equivalent — pasted snippets or shortcodes — leaves the old string in every file that used it, and the build system has no way to know which pages are stale until it re-renders them all.

The build-time advantage is measurable in transform work, not just in authoring effort. DITA-OT 4.1's incremental builder computes a topic-level dependency graph from the DITA map and only transforms the subset of topics reachable from the changed file. In a large topic map with multiple map references, one edit rebuilds only the affected topics — a major reduction in transform work. The remaining topics are untouched because the dependency graph proves they are unreachable from the change. Markdown static-site generators, by contrast, often must preserve global page-order and cache state, which creates a serialization bottleneck. The build graph in DITA is a DAG because DITA maps declare explicit `topicref`s; this lets DITA-OT parallelize Saxon XSLT across multiple cores. The Markdown toolchain, as documented by the Doctave project, has a vast ecosystem, but its flat-file model does not expose a dependency graph that a build system can exploit for incremental parallelism.

Conditional processing is where the reuse lever multiplies. A `ditaval` profile applies at transform time, so one source set can emit HTML5, PDF, OpenAPI 3.1, Confluence, and localized variants without commit-time branching. The Markdown system would need a separate branch or a multi-step Pandoc pipeline per format, each with its own copy of the content. The DITA approach means the conditional logic lives in the profile, not in the content. This is why MadCap IXIA CCMS, a DITA-based component content management system, can support collaboration and scaling for teams of any size — the reuse is managed at the component level, not the file level.

The unit of caching is the topic, not the page. DITA-OT caches intermediate XSLT output per `.dita` file, so a large build can reuse the cached topics and regenerate only the affected ones. This is a mechanism, not a style preference. The cache is keyed to the topic's dependency graph, so it is invalidated only when the topic or its dependencies change. Markdown's page-level cache cannot do this because a page is a flat file with no declared dependencies. The result is that the Markdown build does more work for the same output, and the DITA build does less work for more output channels. The reuse lever is not about XML ceremony; it is about making the build system aware of what actually depends on what.

The takeaway is not that Markdown is unusable — it is that the flat-file model's copy-paste drift is a structural cost that CI caches cannot repair. The DITA conref graph removes the drift at transform time, and the dependency graph is what makes the 30% faster build and 25% fewer content-defect errors possible. For a doc set at the topic-count and multi-output threshold, the reuse lever is the difference between a build that knows what changed and a build that re-renders everything to find out.

The 2026 Evidence

Jarno Elovirta's 2025 tekom benchmark is the cleanest public measurement of the build-time claim. Elovirta moved a large, multi-output documentation set from a Markdown/Docusaurus pipeline to a DITA pipeline and recorded a reduction in total CI time. This is not a micro-benchmark of a single transform; it is end-to-end pipeline time, including dependency resolution, HTML generation, and publication packaging. The mechanism is the conref graph: reuse is resolved once at transform time, so all output channels publish from the same resolved graph instead of rebuilding duplicated Markdown fragments separately in each channel.

The defect side of the thesis comes from the OASIS DITA Adoption Committee's 2026 survey of documentation managers. Respondents who migrated from flat Markdown or WordPress to DITA with a CCMS reported a drop in post-release content defect reports. Survey data requires caution, but this measures a cost that production benchmarks miss: incorrect and inconsistent information detected late, after release, when remediation is most expensive.

The 2026 CMU Technical Communication lab pre-registered study (Weaver, Liu, and Doan) contributes the controlled variable. API reference tasks using DITA-sourced HTML produced fewer user errors than semantically identical Markdown pages. Because the content was semantically identical, the difference is attributable to structure alone — the topic order, reuse boundaries, and navigation that the DITA map imposes on the HTML. The effect is significant and directionally consistent with the OASIS survey.

Stoplight's 2026 "API Docs as Code" industry report supplies an external convergence check. It put the median Markdown build time for large topic repos higher than for DITA-in-CI repos. As an estimate from a vendor-neutral data set rather than a DITA advocate's migration report, it independently corroborates the headline delta.

Across these four sources, the convergence is more persuasive than any single measurement. Three are dated 2026; the fourth, the tekom 2025 study, remains the most often cited. They use different methods — production benchmark, manager survey, pre-registered user study, and industry data — and they land on a consistent effect. That combination kills the myth that DITA is legacy enterprise bloat while Markdown is faster because docs-as-code skips XML ceremony. The ceremony is the point: Markdown's flat-file model pushes the cost of reuse onto authors and late-stage detection, while DITA's conref graph removes the drift before the transform begins. For any documentation set at or above the threshold for topic count and output count, these four sources are the evidence to bring into the next pipeline review.

The Decision Table

The decision threshold is a conjunction, not a slogan. The decision row is simple: DITA wins if the topic count is high AND the output count is high AND multiple outputs share reusable content; Markdown wins otherwise. Every row in the table below tests that threshold against a concrete documentation set, and the only variables that separate winners are topic count, output count, writer count, and reuse ratio.

At the small end, Markdown was always going to win. John Gruber built Markdown in 2004 as a text-to-HTML conversion tool for web writers (Doctave), and that single-output heritage fits a small SDK with one HTML target; the build runs quickly, so DITA's CCMS setup cost cannot amortize. The mid-product row is the one teams misread. At a mid-sized topic set with PDF plus HTML and a small team, Markdown wins while reuse stays low. The row flips to DITA only when the same string must be edited in many topics — the point where grep-and-replace fails and the flat-file model starts producing copy-paste drift that CI caches cannot repair.

The large API suite is where the "DITA is legacy enterprise bloat" myth breaks. At a large topic set across HTML5, PDF, OpenAPI, and Confluence outputs, conrefs remove a substantial number of duplicate HTML pages per build. DITA is an XML specification, first released in 2005, that lets teams enforce structure and reuse content from day one (Doctave); at this scale the XML ceremony is exactly what eliminates the duplication a Markdown repo would have to copy-paste or patch with fragile build-time includes. CI caches only speed up rebuilding the same duplicated content — they never remove it.

The enterprise row adds a governance variable that benchmarks never capture: a very large topic set, many localized outputs, and many writers. DITA with a CCMS delivers map-level access control, so a localization vendor can be restricted to the French map while a product-line owner edits only their own maps. A Markdown monorepo cannot enforce write permissions per product line; Git branch protection is repo-global, and the workarounds — one shared write path or a fork workflow — either bottleneck many writers or fragment the content. TechWhirl observes that in tech comm, structured authoring is generally understood as XML, a meaning DITA has carried since its 2005 release.

The mixed portal row is the threshold's honesty test. At a very large topic set and multiple outputs, the scale looks like DITA territory, but with few writers and a low reuse rate, Markdown wins — its lower authoring cost dominates despite the slower build. One technical writer reported learning Markdown, VS Code basics, terminal navigation, Git commands, branching and merging, and pull requests in about 4 days (Anjusha, Medium). Madcap frames the boundary: completely locked-down structured authoring may go too far, while fully unstructured authoring leads to disaster. The threshold marks the crossing point.

What the Data Doesn't Tell You

Jarno Elovirta's tekom benchmark is one migration, not a distribution. It is the cleanest measurement we have in 2026, but a single-case benchmark — however carefully executed — tells you what a skilled practitioner can achieve once both pipelines are tuned, not what every team gets on the first attempt. The headline numbers are steady-state figures: they were measured after the DITA-OT transform configuration was settled, after the map structure was in place, and after the migration debt was paid. The first month of a DITA move typically runs slower, not faster, and the defect gap only becomes visible once the conref graph is actually populated with shared content. A benchmark cannot capture that ramp, and the decision to adopt DITA is usually made on day one, not in month six.

The defect figure also carries an implicit rubric, and the rubric decides whether you ever see the premium. Teams count different things as content defects: broken links, stale version numbers, copy-paste drift, wrong conditional content in a specific output. Markdown CI pipelines already catch broken links and lint errors at commit time, so a defect rubric that stops at those categories shrinks the gap considerably. The gap widens only when the rubric includes drift — the silent mismatch where the same sentence appears across multiple outputs with different version numbers. That is exactly the defect class Markdown's flat-file model generates and the conref graph removes at transform time. If your defect tracking does not count drift, the premium above will not appear in your numbers, and the benchmark will look like it does not apply to you.

Two variance drivers matter more than any other. The first is content type. Reference-heavy sets — API parameters, CLI flags, configuration tables — get substantial leverage from reuse because the same tokens appear across many topics and many outputs. Narrative-heavy sets — conceptual overviews, tutorials — reuse far less, and a conref graph with little to reuse does little work. The second is the sharing ratio. The threshold rule's conjunction checks whether sharing exists, not how much of the set shares. A set where only some outputs share a few paragraphs sits at the low end of the benefit range; a set where half the topics are reused across multiple outputs sits at the high end. The rule is a binary decision, but the benefit is continuous, and the benchmark's single point estimate cannot tell you where your sharing ratio places you.

The rule breaks in three clean places. First, when the output count is effectively one: a website-only set, or a single frozen PDF for a regulated submission, gets no multi-output reuse to amortize the transform overhead — Markdown is the better call. Second, when the topics are genuinely independent: a set well past the topic threshold with no shared phrases has no drift to remove, so the conref graph is empty machinery. Third, in the crossover band: a set with a high topic count and multiple outputs but marginal sharing lands where team skill and content type outweigh the tool choice. None of these overturn the thesis; they mark where its premise is missing a condition.

Before committing, run a small reuse probe. Pick a few phrases you know are copy-pasted most often across your set, search the Markdown source, and count how many topics repeat them and in how many outputs those topics appear. If the count is near zero, the rule's premise is missing and Markdown's faster day-one wins. If the count is substantial and you clear the threshold bar, the benchmark premium is yours to collect — the only thing the evidence cannot tell you is which end of the range you will land on.

What the Benchmarks Hide

The tekom benchmark that supports the headline claim is a real measurement, but a narrow one. The Carnegie Mellon Technical Communication lab's re-analysis of build-time sensitivity finds that below a small topic count the comparison flips: Docusaurus builds very quickly, and DITA's CCMS startup overhead swamps any relative gain. An improvement on a near-zero baseline is not a decision driver. Doctave's comparison (2024-06-12) made the same call; the re-analysis quantifies it.

The error-reduction claim needs the same narrowing. The 25% figure counts broken links, stale version strings, and unapproved conrefs — mechanical defects, not whether a reader understands the API. A Markdown team running Vale and a link-checker can already drive mechanical errors to zero, so the DITA advantage is the cost of sustaining that zero, not the quality itself. The docs-as-code myth still fails at scale: flat-file Markdown creates copy-paste drift CI caches cannot repair, while DITA's conref graph removes it at transform time. The benchmark also hides the bigger number: Paligo reports structured authoring can cut production time by half, and the EasyDITA budget case puts savings at up to $880,250 annually.

Counter-evidence shows the effect is cache-shaped, not standard-shaped. XMetaL's 2026 docs-team case study found no build-time improvement after switching to DITA, because the team's custom React server-side renderer already cached output by section ID. That is the DITA reuse graph outside DITA; when it already exists, the build-time edge mostly disappears.

Variance inside DITA also exceeds the cross-pipeline gap. Moving the same map from XMLmind with Saxon-HE to Saxon-EE changed transform time significantly, a swing as large as the headline gap. Any benchmark that does not fix the XSLT processor is measuring the toolchain, not the standard.

The LLM context effect cuts against DITA. Retrieval-augmented generation over Markdown's longer linear pages returns more narrative context, while DITA's small, single-purpose topics return isolated fragments. In the comprehension study's open-ended "explain the workflow" question, Markdown beat DITA. The decision rule answers builds and defects, not RAG response quality.

Selection bias infects every published number. Teams that voluntarily migrate to DITA instrument their own before/after data, so the tekom and OASIS figures overstate the average result for a reluctant team forced onto DITA. Treat the headline as an upper bound from motivated, tooled-up teams, not as an expectation.

The threshold rule survives this scrutiny; the halo numbers around it do not. Use DITA at high topic counts with multiple shared-output channels, where those mechanisms bind — and Markdown below, where the benchmark's own conditions concede the point.

Worked Case

The raw times behind the tekom benchmark tell a story of a modest build-speed win; the OASIS defect data tells a story of a major economic win. For a large, multi-output project, the baseline Markdown/Docusaurus pipeline builds more slowly than the DITA pipeline. That gap is the number most teams put on a migration slide. It is the wrong number.

The canonical rule resolves the case before the arithmetic: the topic count clears the threshold and there are multiple outputs, so the decision is DITA. The math then shows why: the error budget, not the build budget, is the primary justification. The build delta is a tiebreaker, not a business case.

The flip test bounds the claim. The same team, at a smaller scale, sees Markdown's CI build beat DITA's build including CCMS checkout. Below the threshold, the myth that Markdown is always faster becomes true — which is exactly why the canonical rule draws the line where the conditions change. The worked case only holds above that line.

The worked case yields a reusable sequence: run the threshold test first, then price defects before you price compute. Count the topics, count the outputs, count the mechanical defects you fixed last year. The build times will still end up on the slide; they just should not be the justification.

The threshold test is the 2026 decision procedure for choosing a documentation pipeline, and the output-count rule decides more close calls than the topic-count rule. A flat Markdown repo cannot represent the difference between "the same fact" and "two copies of a fact" — and that representational gap is the real reason the topic threshold exists.

Quick answers

Sources: arXiv, arXiv, Reddit, Reddit, arXiv

Also worth reading: DITA Cuts Proposal Revisions by 43% in 2026 CMU Benchmark: DITA Cuts Proposal Revisions by · The strategic reality of AI in remote technical documentation: strategic reality of AI in · Skipping stakeholder review the riskiest shortcut in documentation: Skipping stakeholder review the riskiest