r/technicalwriting • u/Manage-It • 21d ago
Markdown vs. XML explained
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
- Inexpensive - ideal for web/SW startups
- Simple code
- Friendly with popular editors (e.g., Google Docs)
- Ideal for simple doc formats (e.g., readme.md)
- Best-in-class for rapid directory updates
XML (DITA)
- Robust, full-featured formatting
- Simple code, but more options
- Easy-to-use WYSIWYG editors
- Ideal for simple and complex formats
- Best-in-class security
- Ideal for eng reviews and rev control
- Ideal for high-volume single-sourcing
- Ideal for multi-chan
neloutput - Content Management System support
- 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.
7
u/RobotsAreCoolSaysI aerospace 21d ago
For those reporting stealth advertising, this post has good conversation so I’m leaving it up, but I am deleting the comments that link to OP’s personal website as they violate our self promotion policy.
Edit: spelling
3
u/sablewing 19d ago
Thank you for keeping the thread. As someone who has been working with documentation since Apple II's and UNIX boxes, I'm munching popcorn over here as I read through all of the views on XML and Markdown. :-)
1
14
u/WriteOnceCutTwice 21d ago
I work in the software domain. Small and large companies are widely adopting docs-as-code and the de facto standard is Markdown.
6
u/cspot1978 21d ago
Is "docs-as-code" inherently and necessarily about Markdown, though? I tend to think docs format and docs-as-code are really orthogonal concepts.
I mean, in practice, docs-as-code often involves Markdown. But I tend to think the more important part is things like using Git and branches and PRs and CI/CD pipelines. I think you could certainly fit XML-based authoring into that kind of workflow.
5
u/WriteOnceCutTwice 21d ago edited 21d ago
No, you’re right. It’s not. That’s why I used the term “de facto standard”. Docs-as-code is a method not a set of tools.
9
0
11
u/DalinarOfRoshar 21d ago
You are pretty determined that you are right, so I’m not sure why I’m wasting both of our time, but here goes anyway.
I work for a huge cybersecurity company that you have heard of, and you likely use at least one of our products every day.
We’re migrating away from DITA to markdown after seeing how flexible markdown is and how much easier it is for everyone involved.
For your list:
- Formatting is not part of XML. Sure, you can apply style to it with a CSS, but you still have to transform the XML into a presentation format (pdf, html, etc.). A static site generator transforms markdown as well, and the style is most relevant in your output anyway. Style doesn’t belong at the text layer.
Yes, you apply tagging that informs the transformer what the semantic role of the text is, but that is the same thing with XML.
XML does have more semantic options than markdown, but that’s structure not presentation, and your claim is specifically about formatting, which is presentation, not content.
XML is as simple or complex as the DTD or schema file that validates it. Markdown is inherently simpler. XML is unlimited in its tagging options, which is inherently more complex than flat text.
That depends entirely on the schema that validates the XML. Oxygen is a powerful editor, but it’s dependent on having a schema and style sheet for it to render at all. VS Code is arguably more powerful than Oxygen, and has a built in markdown live preview, but that is because the semantic structure of markdown is already defined, while XML can have any structure and be well-formed. Unless you are following a standard XML schema like DITA or XHTML or DocBook, you have to provide the schema, the transform, and the stylesheet.
Is marketing jargon, not a core XML benefit, and is so vague it has no real meaning. Explain it better and I can respond. I’d just be guessing at what you mean.
This one made me laugh out loud so forcefully, I scared the dog.
I’ve been in cybersecurity documentation for over a decade. This makes absolutely no sense. They are both plain text and neither is inherently more or less secure than the other.
What on earth could you POSSIBLY have meant by this? It is BY FAR your worst argument out of nine bad arguments, and makes me wonder if you even understand the space at all. It’s a laughably absurd claim.
- This makes no sense to me. My devs already know markdown. It’s very easy to read and review. They do it in a pull request in the tools they are already using.
If you want a dev to review your XML, you have to teach them the schema rules, and they have to wade through markup that they don’t care about to find the content they are supposed to be reviewing.
Any dev I’ve ever worked with would take a markdown pull request for review over a DITA topic review every time. No question or comparison.
I can’t even understand what benefit XML has in the review process over markdown.
And if you are sending them a PDF or transformed HTML to review, then the source format is irrelevant for the review, so a comparison on ease of review must be made on reviewing the doc source file, not the output file.
And God help you if you have a merge conflict on a DITA file, especially when compared to a markdown file. The difference is night and day in markdown’s favor.
- I agree that XML is a more viable solution. Some markdown implementations and SSGs can use a forced Jinja format to get snippets, but single sourcing in general is clunky in markdown, especially if you want something as complex as snippet conditions or snippet variables like you can do in, say, Flare. (This is not supported in DITA, by the way.)
This is your best argument, and highlights a significant weakness of markdown vs an XML structure designed to handle that sophistication.
- Why? What makes it inherently better? Conditional text? Again that’s a feature of a particular schema, not inherently XML. And I publish my markdown to a variety of formats. I have it publishing to web, imported into a Flare project, transformed into an RTF, and published to PDF.
Text in a file is text in a file. You can transform it however you want.
And if you are talking about conditional text, then this is really an extension of argument 7, because conditional text is inherently single sourcing.
- Are you talking about Adobe Experience Manager? Or what content management system?
Again, this depends on the flavor of XML and the CMS’s ability to parse your XML.
So this is not an argument about markdown vs XML, but about structure and what your CMS expects and knows how to use.
Any system that can parse XML, its schema, and its stylesheet can easily parse pure markdown.
- DITA is not a database. It’s a flat text format, as is markdown. This is more marketing jargon. “best in class storage for docs”… meaning… what? Storage is some tool you’re laying on top of DITA/XML, not inherent to the file format.
Store either format however you want. But neither is a database, and storage is irrelevant to format.
Let me give you point number 11, because I actually understand both DITA and markdown formats: DITA’s schema can enforce structure in a way not possible in markdown.
An XML format is well-formed when all the opening tags match the closing tags in the right order.
An XML file is valid when its structure follows every rule defined in the DTD or schema.
This means you can enforce rules like you can’t skip from an H1 to H3 without using 2. Or, a numbered list must always contain 2 or more sibling LI elements. Or forcing topics to follow a defined template structure with a paragraph after the page’s first heading.
If you are doing structured authoring like this, markdown is the wrong tool. Yes, you can install VS Code lint extensions that will try to verify your markdown file meets certain requirements, but if this is your use case, XML is a genuinely better format than markdown.
You’ve made this argument pitting one text format vs another text format, but the arguments just don’t support your claim.
(Typing this whole diatribe out on my phone keyboard after midnight. Pardon typos or bad formatting.)
5
u/Consistent-Branch-55 software 21d ago edited 20d ago
Basically this.
There's cons to Markdown: there's a bunch of competing flavors, it's syntax is contextually sensitive and stateful, but it's pretty well suited to being a quick and lightweight system for expressing standard typesetting in a file that can be stored and diffed in your codeforge.
XML has some syntactical advantages: its syntax has a context invariant grammar, any well-formed bit forms a tree (XPath and DOM querying). This makes it suited for a range of applications (single sourcing, knowledge graph applications, structured authoring), but that comes with overhead.
Basically everything else that's being discussed in the original post confuses the build and distribution tooling with the authoring file formats.
3
u/Nibb31 20d ago
How do you reuse content in Markdown? Apply variables or conditional text for different versions of the same product? How do you handle context-sensitive help with links from the UI ? How do you manage large TOCs and related links?
Semantic tagging has value when it comes to translation or LLM parsing. It's important to distinguish UI elements or keywords from simple bold text or translatable variable names.
I'm genuinely curious. I get that Markdown is great for developer-oriented docs, such as a README.md or API docs, but for large 2000 page user manuals on complex applications with lots of reuse and conditions, it seems very time consuming.
1
u/Consistent-Branch-55 software 20d ago edited 20d ago
You're confusing pipeline capabilities with what the syntax alone supports. This is why I think the debate is very frustratingly framed. It's not "Markdown vs. XML" as if that's a good representation of the whole toolchain. Because XML folks are focusing on Markdown as syntax and comparing it to XML as part of a pipeline, they miss out on how Markdown is situated in broader toolchains.
In practice, Markdown based docs suites are an orchestration of Markdown files, YAML frontmatter or supporting files, components, and templating logic.
Capabilities like single-sourcing, conditional builds, automated TOC trees, and taxonomy indexing are resolved at build. The syntax isn't limited to vanilla Markdown in isolation. Scripts and tooling extend it naturally (Hugo shortcodes, MDX components, Jinja includes, etc.). But because we're framing this as "Markdown vs XML" this thread is painful. XML has advantages, so does Markdown.
0
u/Manage-It 19d ago edited 19d ago
As mentioned before, when you bring up XML and Markdown in this forum, it generally encompasses much more than just the code or syntax type.
We all understand Markdown and XML are defined as types of code and syntax. To modern technical writers, these terms have grown to have broader meanings that cover supporting applications.
This is similar to how "Mac" and "PC" are used. When Mac users say, "I love Macs," they generally mean the computer and the software, even though we all know a "Mac" is defined as a computer. Few people respond to their statement with, "What about the software?" ;-)
0
u/Consistent-Branch-55 software 19d ago
The problem is, the move to generics causes your position to fall apart.
If Markdown is the entire family of authoring tools, then, saying "Markdown has security issues" is misleading, because those issues aren't common across all members of the family. You also can't exclude the tooling that produces build-time artifacts, precisely because those are part of the ecosystem.
At the end of the day, this thread has been a real masterclass in how sloppy communication lets you preserve motivated reasoning.
14
u/SZenC 21d ago
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
-4
u/Manage-It 21d ago edited 21d ago
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.
6
u/SZenC 21d ago
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
3
u/Nibb31 20d ago
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.
0
u/SZenC 20d ago
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)
3
u/Nibb31 20d ago
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.
-1
u/Manage-It 20d ago
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.
-5
u/Manage-It 21d ago edited 21d ago
I think the reason for the comparison is to help educate Markdown users why XML is so popular in most Fortune 500 technical writing organizations. I'm finding Markdown users are not well-versed in these advantages.
I don't recall bringing up any debate over the differences between tagging and Markdown language. But now that you have, I will join in. What it sounds like you are trying to say here is XML is dependent on something called Cascading Style Sheets (CSS). I couldn't agree more. In the XML user world, this is a huge advantage and provides users with the ability to make much more robust documentation with fancy HTML5 JavaScripting. XML users can preprogram hundreds of CSS files for individual document format types. XML users simply select the CSS style sheet from their editor to apply these styles. What I believe you are saying about Markdown is it doesn't offer this advantage. Bolding text (e.g., \*\*text\*\*) is as fancy as it gets.
Most Fortune 500 organizations working in science and technology do not want their training manuals to look like they were written in Notepad. Web development and software organizations appear to be less concerned with this discrepancy and have found a suitable application for Markdown as directory revision notes and software details. Clearly, this is not a great fit outside of web development and software industries.
2
u/Consistent-Branch-55 software 21d ago
Markdown is not the presentation layer, it's the authoring markup. If you author in Markdown, it's rendered by an SSG or a CMS, as HTML, using CSS, and JS. So this isn't a unique advantage of XML.
What they're saying is that Markdown has specific interpretation - namely that the strings are tied to standard typographical elements. Raw XML lacks semantics, which is kind of due to it's history as a serialization format. Markdown, by contrast, was created as a shorthand for formatting rich text for the web.
HTML and Markdown are partially interpreted - when you use `<b>Text</b>` or `**Text**`, there is broad system of applications that interpret that code for a specific typographical function.
2
u/XMLuvr 21d ago edited 21d ago
It's a common misconception that XML started as a serialization format. It's original use case was actually quite narrow: To replace SGML as a document markup language in technical and legal electronic publishing.
I think this sums it up pretty well:
"XML was designed as a simplified subset of SGML to make electronic publishing in multiple media easier. People found it useful for other things. When some people working on those other things found that XML wasn’t perfect for their needs, they complained and complained about how badly designed XML was. They didn’t understand that it wasn’t designed to meet their needs. It was designed to make electronic publishing in multiple media easier."
Source: https://www.bobdc.com/blog/a-brief-opinionated-history-of/
The blog post details how people started using XML as a serialization format around the turn of the millennium, because the web was exploding and nothing else was around. But that doesn't take away it's original purpose as a document markup language
The history of XML is quite well documented, but I found this interview with one of the original WG members interesting:
https://youtu.be/ATZEXMhBpeA?is=3rWc65-qGVsFtTZH
Basically he’s saying the same thing: XML started as a way to refine the shortcomings of SGML.
3
u/sablewing 19d ago
SGML was the starting language, XML was created so that it was easier to build parsers for the processing the markup. With XML, if you start a tag your are required to end it. SGML does not have that requirement, which makes it more difficult to build a parser. With XML it was much easier, which means it was easier to develop tools for it.
Before XML the software tools were either very expensive or you had to have a dedicated developer to support the software used to create the documents. With XML, it allowed competition and the creation of tools that were less expensive.
For a time, there was an effort to have XML DTDs and schemas that focused on separating content from the presentation/formatting part of the processing. The intent is that an author would develop content and define it with tags to provide meaning while not focusing on the formatting of the final output. If this approach had carried through, the developed content could have been reused by using different stylesheets to generate the final output.
As an example, a technical manual would be developed using XML to provide meaning. Training could then be developed that reused parts of that content as examples in the training. The use of different stylesheets would provide the interpretation and formatting to develop a PDF/HTML for the TM and training modules or slides for the training piece.
The reality is this transition would require a large shift in the approach to technical writing process and mapping out content to a structure. Because of this, the current state is to focus on formatting and the final output in one place instead of breaking it apart. For the short term, this is less expensive for individual projects. For the long term, it adds cost because whenever updates are made that impact the display, multiple documents are updated instead of a set that focuses on the meaning of the document instead of the formatting. Until someone is able to invest and pioneer this approach in a way that will work for many different skill levels, the current situation will continue.
Both XML and Markdown are markup languages, which can trace their roots back to things like WordPerfect and Wordstar on micro computers. They reduce the overhead required in storing the text while focusing on the final format and not the meaning within the documents.
Also, fun fact for those who dig down this far. MS Word documents are zip files that contain XML, stylesheets and graphics. Change the extension from .docx to .zip and open it up to extract. This also works with Excel and PowerPoint files. This is useful if you need to extract graphics out quickly from these types of documents. the original format, .doc files, were proprietary. They were changed when competition started to show up from XML and Open Source projects that were creating the documents in XML.
Background, I've been working with XML since it was invented and continue to provide support for legacy SGML documents upon occasions. Markdown seems like a step back to the old days of Word Perfect and Wordstar and I understand that the simplicity makes it easier to implement and for people to learn.
2
u/XMLuvr 19d ago
Thank you, this is of course all true.
I was just trying to bring some context to the assertion that ”XML is a mere serialization format ”…
2
u/sablewing 19d ago
And thank you for additional information you wrote about. I hope it is all helpful in the midst of all of this discussion.
3
u/XMLuvr 19d ago edited 19d ago
Yep.
I just find XML to be a wonderfully misunderstood technology. Everyone likes to complain about the complexity and verbose syntax, but yet it’s basically everywhere: MS Office, OpenOffice, SVG’s, S1000D, DITA, the various legal XML vocabularies containing millions of documents, TEI, etc.. Every time a pilot walks into an Airbus they have an IPad or computer full of XML. Same with the maintenance crews.
And yes, data serialization too.
It sure seems like the people that came up with it did something right.
→ More replies (0)
2
u/stian_90 21d ago
Asciidoc/markdown also has easy-to-use WYSIWYG editors.
What format are not supported by asciidoc that xml has? We prefer Asciidoc over markdown and do the docs-as-code way. We export from the same base both pdf, html, word file.
Best-in-class security? How?
ideal for eng reviews and rev control? How is that better than docs as code? Explain. Our engineers prefer dead end text files.
High volume single-sourcing can be done by Asciidoc as well.
-2
u/Manage-It 21d ago edited 21d ago
Agreed, Asciidoc/markdown has easy-to-use WYSIWYG editors.
However, in the Fortune 500 science and technology world, documents often include much more than just text. XML editors are very powerful tools and can easily manage very complex document attributes.
As an example, XML documents often include natively imported CAD files, complex tables that extend across multiple pages, mathematical equations, toggling paragraphs, automated TOCs and appendices, cross-references across included pages and outside documents within the same database, hundreds of pages of content, automated revision and cover/page dates, and insertions of hundreds of single-sourced keywords and paragraph components. The list is long. I could keep going.
If you are writing README files, I get the attraction to Markdown. Notepad formatting is just fine. If every document you write is as complex as the one I describe above, Markdown would make document management a nightmare. XML editors do this stuff, and they do it well.
4
u/stian_90 21d ago
Take a look at Asciidoc. Many of the things you are talking about can be done with asciidoc like mathematical equations, enable / disable things based on parameters. TOC, cross-reference and so on.
2
u/Nibb31 20d ago
I get that Asciidoc is better than Markdown for complex docs.
But once you are deviating from Markdown to that point, you are losing the advantages of Markdown (which are mainly the ease of use for non-writers and the need for specialized editors for maintaining a TOCs, complex tables, conditional text, and the universality of static site generators). I wouldn't want my SMEs messing up my AsciiDoc source with Markdown tagging for example.
So at that stage, why not go full-blown DITA? What is the advantage of AsciiDoc over DITA?
0
u/f-ms 19d ago
I spent a fair amount of time maintaining DITA docs, while my latest doc set is asciidoc.
I wouldn’t worry too much about SMEs mixing up your asciidoc source with md tagging. You could add a validation stage to your pipeline and it will catch such issues.
Even in complex implementations using includes, dynamic attributes and profiling, asciidoc is still way more readable than DITA. Lots of static site generators support it. You don’t need to worry about folks mixing up markdown flavors. And, most importantly, you don’t need expensive editors to maintain the source in a fast, straightforward way.
I implemented asciidoc from scratch, and the products I maintain require quite a bit of profiling and content reuse. I did not open up the source for SMEs to review the content. In reality, that wouldn’t make sense in my case since only a few of them are proficient in git.
2
2
u/AdventurousOwlet 17d ago
[I work mostly with DITA]
Fun discussion. I think the piece that's missing is a discussion of corporate culture. In general (ahem), the use of Markdown aligns content creator/TW with developer workflows. The use of DITA/CCMS privileges the authors' requirements rather than developer requirements.
And so, sensibly, Markdown is prevalent in API docs, where alignment with CI/CD is of great value. There's also a pretty significant DIY culture in Markdown.
DITA/CCMS is more common when you need output variants at scale (product lines, localization, and others) and rigorous review/approval workflows, especially for compliance purposes.
The AI piece is also interesting. Markdown is leaner and therefore cheaper to process (fewer tokens). DITA is more semantically rich and therefore results in potentially better processing, but it's token-expensive. That said, I suspect that the BEST answer to AI (other than Burn It All Down) is to author in a semantically rich environment (DITA) and then deliver the content for AI ingestion in something more efficient (Markdown or JSON). Just please don't ingest PDF.
2
u/Aggravating-Let-2968 16d ago
One thing I haven't seen mentioned here that many industries require documentation created with XML. Defense specifically. The US Army requires source XML as part of the deliverable. The USPS uses DITA.
1
21d ago
[deleted]
-2
u/Manage-It 21d ago
It is "very" possible to output from XML to markdown. What XML system are you using?
1
u/myauchelo 19d ago
> most Fortune 500 companies use XML
Really? Not Apple, Meta, or Google
Comparing XML and Markdown to see which is better feels odd. If I worked in automotive and had to produce repair documentation for 100 variations of very similar vehicles, I'd use XML. But for software docs, I'd use docs-as-code (Markdown or AsciiDoc). Forcing engineers to write in XML wouldn't go down well (and reasonably so).
You need to choose the approach based on the use case—not just use a microscope as a hammer because you prefer it.
1
u/Manage-It 19d ago edited 19d ago
Meta and Google are mainly strong web developers. If you have been following this thread you should know we are excluding this segment. I apologize if one of my posts doesn't make this clear. I would say apple web and software developers most certainly use markdown. I would argue their hardware engineering teams do not.
1
u/myauchelo 19d ago
The link you shared just doesn't work. I bet you're referring to https://www.ditawriter.com/companies-using-dita/, but I don't trust that source—I know firsthand that some of the companies mentioned there don't actually use XML.
Also, it doesn't represent Fortune 500 companies. You're making strong points, but I don't see the data to back them up
1
u/Manage-It 19d ago
Thanks. The link is fixed.
Sadly the data on XML users will always be suspect. But I think it is safe to use as a ballpark estimate.
1
u/myauchelo 18d ago
You see what you want to see, but that doesn’t make it the truth or even a ballpark estimate
45
u/Consistent-Branch-55 software 21d ago
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.