Word versus Markdown: more than mere semantics

Our default content publishing workflow is terribly broken. We’ve all been trained to make paper, yet today, content authored once is more commonly consumed in multiple formats, and rarely, if ever, does it embody physical form. Put another way, our go-to content authoring workflow remains relatively unchanged since it was conceived in the early 80s.

Screenshot of Microsoft Word 1.0

I’m asked regularly by government employees — knowledge workers who fire up a desktop word processor as the first step to any project — for an automated pipeline to convert Microsoft Word documents to Markdown, the lingua franca of the internet, but as my recent foray into building just such a converter proves, it’s not that simple.

Markdown isn’t just an alternative format. Markdown forces you to write for the web.

In the beginning, there was paper

The first desktop word processors had a simple task: they were designed to make paper. We didn’t have email or a vibrant internet sharing digital documents to worry about. The creators of the first desktop word processors simply mirrored the dominant workflow of the time: the typewriter. The final output — the sole embodiment — was physical, and all that mattered was what the document looked like.

Over the past three decades, however, how we consume content has changed dramatically, yet, how we author content remains relatively unchanged. Put another way, the internet is a fundamentally different animal than the desktop. You can’t simply take a desktop format and put it online, and “converting” a document to Markdown doesn’t do much to solve that.

Separating content from presentation

Desktop formats are a shallow format — all they care about are looks. Desktop publishing software inextricably marries content and presentation. The information you input can only be consumed in one form, and that one form is defined by the medium, in most cases, paper, or more recently, their digital analog, faux margins and all.

When you blindly optimize for one thing — appearances — behind the scenes there’s a lot that goes unattended and it becomes increasingly complex to perform even the most simple of tasks. Extracting your content becomes tantamount to finding a needle in a purpose-built, legacy haystack.

Put another way, in taking a look at this sample Word Document, given the same content represented identically in various formats, as little as less than one quarter of one percent of the file is actually dedicated to storing content:

Format Size %
———— —————- ——-
Word 33621 bytes 100%
HTML 1359 bytes 4.04%
Markdown 80 bytes 0.24%

Exposing author intent

Once content and presentation are decoupled, content written for the web exposes author intent through semantic markup — markup which describes the relationship between elements, not simply their visual representation. It’s not simply that a given line is bold or a larger font size, but memorialized in the document itself is that that given line is a heading, a heading which describes the content that follows.

Take a look at how markdown represents an unordered list, for example:

* One
* Two
* Three

Simplicity aside, the markup represents a grouping with three elements. We, as humans, can tell that those are three parts of a set, and a computer can as well. Now here’s how Microsoft Word conveys the same exact information, at least when exported as HTML:

&lt;p class=MsoListParagraphCxSpFirst style='text-indent:-.25in;mso-list:l0 level1 lfo1'>&lt;![if !supportLists]><span
style='font-family:Symbol;mso-fareast-font-family:Symbol;mso-bidi-font-family:
Symbol'><span style='mso-list:Ignore'><span style='font:7.0pt "Times New Roman"'>     
</span></span></span>&lt;![endif]>One</p>

&lt;p class=MsoListParagraphCxSpMiddle style='text-indent:-.25in;mso-list:l0 level1 lfo1'>&lt;![if !supportLists]><span
style='font-family:Symbol;mso-fareast-font-family:Symbol;mso-bidi-font-family:
Symbol'><span style='mso-list:Ignore'><span style='font:7.0pt "Times New Roman"'>     
</span></span></span>&lt;![endif]>Two</p>

&lt;p class=MsoListParagraphCxSpLast style='text-indent:-.25in;mso-list:l0 level1 lfo1'>&lt;![if !supportLists]><span
style='font-family:Symbol;mso-fareast-font-family:Symbol;mso-bidi-font-family:
Symbol'><span style='mso-list:Ignore'><span style='font:7.0pt "Times New Roman"'>     
</span></span></span>&lt;![endif]>Three</p>

There’s two things you’ll notice there. First, the markup isn’t semantic, meaning the presentation information is intermingled with the content, rendering the author’s intent indiscernible and using the content in any other context an increasingly difficult goal.

Second, there’s a lot of proprietary metadata in there (everything that’s orange or red), useful only for parsing within Microsoft Word. Again, rendering the content as alien anywhere other than its original context, paper.

Jailbreaking content

There’s a reason that content authored on the desktop is most commonly shared online as a PDF — a format designed to mimic the properties of paper as closely as possible. Once the content’s in a paper-based format, it’s stuck there forever.

If there’s one thing I’ve learned trying to convert Word documents to Markdown, it’s that Markdown is not an alternative to traditional desktop formats. It’s an entirely different animal. It’s both machine- and human-readable, but more importantly, it forces you to author content openly, semantically, and for an internet-based world.

Next time you begin a new project for which the internet, not paper is the primary output, think twice before firing up that desktop publishing platform. You’ll gain more than mere semantics.

benbalter

Named one of the top 25 most influential people in government and technology and Fed 50’s Disruptor of the Year, described by the US Chief Technology Officer as one of “the baddest of the badass innovators,” and winner of the Open Source People’s Choice Award, Ben Balter is a Product Manager at GitHub, the world’s largest software development network. Previously, Ben served as GitHub’s Government Evangelist, leading the efforts to encourage government at all levels to adopt open source philosophies for code, for data, and for policy development. More about the author →

This content is open source.
Please help improve it.