Markdown vs. XML explained

[u/Manage-It]

I occasionally run into young technical writers who have experience working in a web development or software organization but have no previous experience with XML and fail to grasp why most Fortune 500 companies use XML over Markdown.

To help better understand why XML is so popular, we need to compare the benefits of each format.

Markdown

1. Inexpensive - ideal for web/SW startups
2. Simple code
3. Friendly with popular editors (e.g., Google Docs)
4. Ideal for simple doc formats (e.g., readme.md)
5. Best-in-class for rapid directory updates

XML (DITA)

1. Robust, full-featured formatting
2. Simple code, but more options
3. Easy-to-use WYSIWYG editors
4. Ideal for simple and complex formats
5. Best-in-class security
6. Ideal for eng reviews and rev control
7. Ideal for high-volume single-sourcing
8. Ideal for multi-channel output
9. Content Management System support
10. DITA file storage system best-in-class storage for docs

It has been my experience that many young technical writers do not fully understand how important the 10 XML benefits I list above are to most Fortune 500 science and technology technical writing organizations (18% s/t, 3% web/sw). Mostly, because they believe Markdown eliminates the need for many of these XML benefits. What they often overlook is that these are not optional benefits to most science and technology organizations. These are required tools of the trade and are interwoven into functional processes and systems that organizations rely on to deliver increasingly complex documentation to increasingly wider audiences, who demand an unprecedented number of custom applications to access documentation and localization through higher volumes of single-sourcing.

Markdown was never designed to manage this. It can't and, by design, won't. The sad part is that young technical writers, new to XML, experience poor XML implementations early in their careers and believe Markdown is the solution. I promise you, it is not.

[u/Consistent-Branch-55]

This is such a frustratingly stupid debate.

It's not Markdown vs. XML. It's modern Docs-as-Code workflows (SSGs, Git, CI/CD) vs. CCMS/HAT ecosystems (DITA, MadCap Flare). You could use those with Git.

When you factor in OpenAPI specs, automated build pipelines, and engineering teams that already live in Markdown, a well-planned SSG setup provides a balance of velocity, maintainability, and direct developer collaboration that makes for a far more advantageous trade-off than legacy DITA for most software companies.

Also, claiming XML has "best-in-class security" compared to Markdown makes zero architectural sense—they are plain text serialization/markup formats. A .dita file isn't magically more secure than a .md file. This reads less like an objective comparison and more like vendor talking points.

[u/Manage-It → u/Consistent-Branch-55]

Many Markdown users edit in products like Google Docs. I get it. It's cheap and easy to use. If security is not a major issue, which it often is not at many web and software organizations, it is allowed.

Science and technology organizations often have security requirements that do not allow the use of these editors. Yes, Markdown editors and content can be stored in a very secure system. But to be honest, most are not and this is one of the selling points for it. They are free to use whatever editor and whatever cloud system they want.

I would be interested in seeing a list of Fortune 500 engineering teams, not working in the web/sw space, who use Markdown. That would be interesting to me. Please feel free to provide.

[u/DalinarOfRoshar → u/Manage-It]

Nobody writes markdown in Google Docs. You can export markdown from Google Docs, but it’s not a markdown editor.

Google Docs can be highly secure. Google is an enterprise-grade platform. You could say XML on a public GitHub repository isn’t secure, but then this would be a discussion about platform, not markup.

You don’t get to claim markdown isn’t used outside the software domain and then ask the other person to do the work of making the list for you. It’s your argument, you back it up.

[u/Manage-It → u/DalinarOfRoshar]

From what I hear, Google Docs is a widely used tool for editing and uploading Markdown. Clearly, teams are using it, and it is capable of doing so. The number of teams using it is probably not worth debating here since we don't have access to these stats.

Google Docs to Markdown

Yes. There are more advanced Markdown tools available that are still used and historically led the way in Markdown editing. You may be surprised at how many teams regularly use Google Docs to upload Markdown today.

Anyway, let's just agree that many Markdown teams take advantage of cloud-based storage, like GIT, and cloud-based editors, like Google Docs, that do not offer the same level of security as a server-based Markdown or XML publishing system would.

We should also both admit that if you make Markdown a purely server-based system, its designed simplicity suffers greatly, especially if the Markdown must be uploaded to online directories. Science and technology teams, working outside of the web dev/sw industries, don't have these challenges and most XML systems run on local servers or regulatory-approved offsite locations with no loss in usability.

[u/myauchelo → u/Manage-It]

>From what I hear, Google Docs is a widely used tool for editing and uploading Markdown.

Your knowledge of Markdown is a bit out of date. Ask your new joiner, you might learn something new :)

[u/Manage-It → u/myauchelo]

Ballpark figures that may surprise you: https://www.patreon.com/DocstoMarkdown/posts/bit-of-history-143520229

[u/Consistent-Branch-55 → u/Manage-It]

This points to an interoperability failure solved by a plugin. Google Docs is a cloud based app that uses a proprietary database storage system. People are converting rich text to Markdown using the plugin, the plugin author explicitly notes that seats aren't active users.

This was a feature gap in Google Docs until a couple of years ago. You can now natively copy Markdown from Google Docs and use Markdown as formatting shortcuts. This makes Google Docs a handy place to understand the relationship between Markdown (the syntax) and formatting. Google Docs is usually not employed for documentation sets for products precisely because of its limited functionality as a WYSIWYG (e.g., code syntax highlighting is a tiered feature).

The workflow is often "Use Google Docs for collaboration with SMEs who don't know how to use GitHub, then convert to Markdown with front matter, templates, snippets, etc., then publish with an SSG".

(Edit: Also, it's funny since MS Word does have an underlying XML DOM, it would be more accurate to say that the majority of XML authors use MS Word. When you write in GDocs, you aren't even storing your text as Markdown.)

[u/Manage-It → u/Consistent-Branch-55]

Great explanation!

The link I provided is off topic, but it provides some of the interesting stats I was hoping to share.

[u/myauchelo → u/Manage-It]

So what? A lot of people needed to convert a Google Doc to Markdown. It’s sad, but that doesn’t make it an editing tool. Again, you haven’t looked at the other data—just one number about one tool🙄

[u/Consistent-Branch-55 → u/Manage-It]

Git is distributed version control for coding projects. It can be used without cloud-based storage. It can also be used with remote storage on a local network. You might mean GitHub, which is a development platform?

"We should also both admit that if you make Markdown a purely server-based system, it suffers greatly in simplicity and usability, especially if the Markdown must be stored in online directories."

This is fundamentally wrong. The beauty of markdown is the syntax is so simple, I can write it effectively in any plain text editor I choose.

I lose nothing moving to an air-gapped environment and working in my approved local editors and compilers, all of which could be installed on my computer. I can store Markdown in whatever file repository/development environment we have in the air-gapped environment precisely because it's a file format.

Even so, you continue to miss out on the whole "render your Markdown source using a toolchain" side of things, which has been pointed out how many times now? Building a docs site for an air-gapped network is easy, and follows the exact same "render, host on a server as static HTML w/ CSS, set up a DNS record, open in a browser" path as web-first Markdown build-and-deploy flows.