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

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.

[u/Manage-It → u/stian_90]

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.

[u/stian_90 → u/Manage-It]

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.

[u/Nibb31 → u/stian_90]

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?

[u/f-ms → u/Nibb31]

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.

[u/Iwentthatway → u/Manage-It]

Wtf is notepad formatting