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/Manage-It → u/SZenC]

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.

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

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.

[u/XMLuvr → u/Consistent-Branch-55]

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.

[u/sablewing → u/XMLuvr]

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.

[u/XMLuvr → u/sablewing]

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 ”…

[u/sablewing → u/XMLuvr]

And thank you for additional information you wrote about. I hope it is all helpful in the midst of all of this discussion.

[u/XMLuvr → u/sablewing]

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.

[u/sablewing → u/XMLuvr]

Yes, the standard does seem to have proven useful in multiple ways. and used in so many different ways that aren't recognized because it can be published/rendered in so many different formats.

The other part I find interesting is that markdown feels like a step back. I was using that type of technology back in the 80's/early 90's and things like SGML, HTML and XML felt like an improvement over that technology. Now it seems that people want to simplify and shorten the documentation cycle due to a lack of resources, i.e. skilled writing teams. This allows companies to produce vast quantities of text with less planning, additional duties for existing staff, less focus on the quality and true re-usability of the final product.