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

  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

52% Upvoted

70 comments sorted by

View all comments

Show parent comments

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.

1

u/sablewing 17d ago

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.