For years, XML-based authoring (DITA, DocBook, custom schemas) was the backbone of enterprise documentation. It gave us structure, reuse, and precision — but also friction.
Now, with software teams moving faster, docs are expected to live in Git, build automatically, and update as often as the product itself.
This post walks through how to move from XML to a Git-based documentation model — and how large teams like Salesforce appear to handle theirs: Git repos, automated markup updates, CI builds, CDN delivery, and search indexing.
1. Understand the Key Differences
| Aspect | XML-Based Docs | Git-Based Docs |
|---|---|---|
| Structure | Heavily structured (DITA topics, maps, schema validation) | Flat or folder-based structure using Markdown files |
| Tools | Uses CCMS, Oxygen, FrameMaker, or similar editors | Uses Git, Markdown editors, static site generators |
| Collaboration | Centralized via CMS workflows | Distributed via Git branches and pull requests |
| Publishing | Uses XML transformations (DITA-OT, XSLT) | Uses static site builds (Eleventy, Hugo, MkDocs, Jekyll) |
| Version Control | Often handled inside CMS | Native Git support |
Before migrating, identify what XML features your team relies on most—such as topic reuse, metadata, or translation workflows—and plan how to replicate or replace them in the new setup.
2. Pick a Modern Stack
A typical setup looks like this:
- Markdown for content (simple and version-friendly)
- MkDocs, or GitBook for building and hosting
- GitHub or GitLab for version control
- Netlify, GitHub Pages, or a CDN for delivery
- Optional Algolia DocSearch for search
If you prefer visual tools, GitBook is a strong bridge for teams used to CMS workflows — it connects directly to Git while giving editors a friendly UI.
3. Convert XML to Markdown
Start small. Use a converter like Pandoc or a lightweight XSLT to move one section at a time.
Add front-matter to carry over key metadata:
4. Automate the Tedious Stuff
You can use Cursor to batch-update markup — a smart approach that avoids hand-editing hundreds of files.
Organize Your Repository
A clean structure helps both writers and CI:
docs/
getting-started/
guides/
api/
assets/
config.ymlKeep shared snippets or variables in a separate folder. If you plan translations, add locale directories like /en/ and /fr/.
6. Build, Review, and Deploy Automatically
Every change should follow a code-style workflow:
- Writer opens a branch and edits Markdown.
- A pull request triggers automatic linting, link checks, and a preview build.
- Reviewers approve in Git.
- On merge, the site builds and deploys to production automatically.
7. Wrapping Up with Key Insights
In this concluding paragraph, summarize the key takeaways from your article, reinforcing the most important ideas discussed. Encourage readers to reflect on the insights shared, or offer actionable advice they can apply in their own lives. This is your chance to leave a lasting impression, so make sure your closing thoughts are impactful and memorable. A strong conclusion not only ties the article together but also inspires readers to engage further.
8. Host and Cache Smartly
For smaller projects, GitHub Pages or Gitlab Pages are fine.
For enterprise-scale traffic, use a CDN such as CloudFront for reliability.
9. Train and Iterate
The biggest shift isn’t technical — it’s cultural.
Writers need to get comfortable with Git, branches, and pull requests. Developers need to treat docs as part of the release pipeline.
Run a small pilot, refine the workflow, and expand gradually.
10. Wrap-Up: Borrow the Best Ideas, Don’t Copy the Tools
The goal is to collaborate well with the development environment. It is also to combine the best practices they use:
- Store docs in Git
- Automate repetitive markup edits
- Use CI to build and publish
- Serve from a CDN
- Index with search and preserve links
Doing this, you’ll lose some XML-specific power, but you’ll gain a faster, more transparent workflow that fits naturally into modern software development.
Leave a Reply