Docs-as-Code
Legacy XML to Markdown migration
Docs-as-Code workflow architect · Nov 2025 – Jan 2026
5,000+ pages · 40% faster deployment · 15+ hours saved weekly.
Designed the migration and the validation pipeline, mapped the XML semantics, and set the conventions the corpus still runs on.
Git · Markdown · Markdownlint · CSpell · XML · MadCap Flare
- Problem
- 150+ legacy XML manuals in a publishing chain slower than the products they described.
- Insight
- Every reviewer caught formatting errors sometimes and missed them sometimes. The work was tedious and endless, and the miss rate tracked how tired people were.
- Result
- A cloud-native Docs-as-Code pipeline with Markdownlint and CSpell in CI, eliminating 100% of formatting defects across 5,000+ pages.
The full story
150+ legacy manuals lived in an XML workflow built for a slower publishing era: author in XML, export by hand, produce output, and wait. The products moved faster than their documentation could describe them, and every deployment carried a tail of formatting defects that reviewers caught inconsistently because catching them was tedious and endless.
The migration moved the whole corpus into a Markdown source in Git, with Markdownlint and CSpell running as automated validation. With that gate in place, a formatting error can no longer reach a published page: the checks run before every merge, and they do not get tired. Across 5,000+ pages the elimination was total.
The delivery gains followed from the same change. Update deployment accelerated by 40%, saving 15+ hours weekly and removing friction for 4 cross-functional teams who had previously queued behind a manual export step. Documentation changes gained the review history, branch-based collaboration, and rollback that code changes already had.
Migrating 150+ manuals is mostly a structural mapping problem: XML carries semantics that Markdown does not express natively, and the mapping has to be decided once and applied consistently rather than negotiated per document.
Key decisions
- Put validation in CI rather than in editorial review. Reviewer attention is the scarcest resource in a documentation team and the worst possible place to spend it on whitespace.
- Map the XML semantics once, up front, instead of per manual. A mapping negotiated document by document produces 150 slightly different conventions and an unmaintainable corpus.
- Migrate by content area, not all at once, proving the pipeline on live content before committing the full 5,000 pages to it.
What it taught me
The lint gate was the easy half. Mapping XML semantics onto Markdown across 150 manuals took most of the schedule, and roughly a dozen constructs had no clean equivalent: conditional profiling, a few table layouts, two cross-reference types. I settled those with a documented convention instead of a perfect mapping, which means anyone maintaining that corpus now has to learn the convention. I think it was the right trade. It is also the decision I would defend least confidently.