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 has barely changed since it was conceived in the early ’80s.

Government employees regularly ask me for an automated pipeline to convert Microsoft Word documents to Markdown, the lingua franca of the internet. These are knowledge workers who fire up a desktop word processor as the first step of any project. But as my 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 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 it has barely changed. Put another way, the internet is a fundamentally different animal than the desktop. You can’t just 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 shallow. All they care about is 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 appearances, a lot goes unattended behind the scenes, and even the simplest tasks get increasingly complex. 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 three formats, less than one quarter of one percent of the file is actually dedicated to storing content:

Exposing author intent#

Once content and presentation are decoupled, content written for the web exposes author intent through semantic markup: markup that describes the relationship between elements, not just their visual representation. It’s not only that a given line is bold or a larger font size, but memorialized in the document itself is that the 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:

<p class=MsoListParagraphCxSpFirst style='text-indent:-.25in;mso-list:l0 level1 lfo1'><![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><![endif]>One</p>

<p class=MsoListParagraphCxSpMiddle style='text-indent:-.25in;mso-list:l0 level1 lfo1'><![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><![endif]>Two</p>

<p class=MsoListParagraphCxSpLast style='text-indent:-.25in;mso-list:l0 level1 lfo1'><![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><![endif]>Three</p>

You’ll notice two things 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 starting with mso-), 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 readable by both machines and humans, 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.