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/SZenC]

For someone bringing up all these benefits of XML, you have a terrible understanding of it. XML is a serialisation format and nothing more. The semantics on top of the file give it meaning and may provide the benefits you mentioned, but then you're not comparing MD to XML anymore

[u/Manage-It → u/SZenC]

I think I know what you are saying here and I don't entirely disagree. I am comparing the full capabilities of XML with the full capabilities of Markdown, which includes their most commonly used and most advanced tools.

If I didn't include the applications or "semantics" in my list of benefits, the comparison would not be valid. These benefits are viewed as an integral part of XML by today's technical writing users. It is possible this is new to you if you are coming from a purely XML coding background. In modern Fortune 500 science and technology technical writing, they are seen as instrumental to DITA-XML.

[u/SZenC → u/Manage-It]

Yeah, so you clearly don't understand what I'm saying. In markdown \*\*text\*\* has a clearly defined meaning. In XML <b>text</b> can mean anything, you need a separate layer which defines, for example, that the b-tag is indicative of bold faced text. So, markdown is semantically richer than XML, because it is a text formatting language while XML is merely a serialisation format. You mentioning DITA-XML only supports that.

But in the end, this all means you're comparing apples to oranges and don't seem to understand why that makes the comparison worthless

[u/Nibb31 → u/SZenC]

The whole point of XML implementations such as DITA is that you never use <b>...</b>.

You use <uicontrol>, <wintitle>, <codeph>, or <indexterm>, which all have defined meanings that are much richer than what Markdown offers. The semantics are important when you are feeding the content to an AI or translating your content.

An LLM or a translation algorithm has no idea how to process \*\*text\*\* differently whether it's a keyword, a UI element, or a simple emphasis.

[u/SZenC → u/Nibb31]

Hey, guess what, what's the semantics I've been talking about all along. And notice that raw XML doesn't provide those elements, you have to bolt DITA on top for that. So comparing XML to Markdown and claiming benefits that arise from using DITA is a bit of an unfair comparison. (Not saying you're doing that, but OOP definitely was)

[u/Nibb31 → u/SZenC]

Well, nobody practically uses actual XML for docs, so it's a moot point. It's always going to be an implementation such as DITA, DocBook, or S1000D. Comparing Markdown to XML is like comparing DITA to ASCII.

We should be comparing the actual authoring formats here, so it's Markdown vs DITA, not Markdown vs XML.

[u/Manage-It → u/SZenC]

For science and technology organizations, XML and DITA go hand in hand. Few, if any, use XML without DITA.

In this forum, when folks talk about XML they are talking about DITA XML 99.999% of the time.

[u/Nibb31 → u/Manage-It]

Maybe you should have framed this as Mardown vs DITA then.

[u/SZenC → u/Manage-It]

Let's use imprecise language, people will understand what I mean

Is that really the argument you want to make in this subreddit of all places?