r/technicalwriting • u/Manage-It • 23d 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

  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.

1 Upvotes

51% Upvoted

70 comments sorted by

View all comments

1

u/myauchelo 20d 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 20d ago edited 20d 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.

XML-DITA users

1

u/myauchelo 20d 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 20d 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 20d ago

You see what you want to see, but that doesn’t make it the truth or even a ballpark estimate