When a lack of style is the most stylish way to write

The case for Markdown, for non-techies

Good writing is all about the words. Considering how the words look is another kind of decision altogether. Sometimes both of those concerns need to be addressed in the same document, but…

Most of the time even minimal styling is not only irrelevant, it’s an actual obstruction to the workflow that will follow your final draft.

When you write in apps such as Microsoft Word, Apple Pages or Google Docs, your words are styled — with a font choice, a font size, and line spacing, and so on — even when you don’t consciously change the text formatting. As a result, it’s all too easy to pay too much attention to how the text is styled and too little to its semantics, its structure.

For the sake of brevity below, I’ll refer to these kind of apps collectively as Word.

Put simply, there are times when style matters and times when it needs to stay out of your text.

Word is the right option when…

The formatted text will be printed directly from Word or a PDF made from it, and those outcomes are the final deliverable.

When that’s the case, go ahead and use Word, because in these cases the way the text is styled matters.

Word is the wrong option when…

The text is going to end up in some other process.

Your text could be:

• Destined for a web CMS via copy/paste
• Have multiple different end uses
• Need to be entered directly into a spreadsheet cell for the purpose of collating and importing a set of texts into a database

In all these cases proprietary styling is a hindrance to integrating the text: it will have to be stripped out and reconsidered.

The web is very particular about text

On the web, the semantics of text are fundamental to HTML, the underlying language of the web.

Done right, HTML is the markup language that grants text structure in a way that is:

• Accessible in the way the reader needs
• Optimally understood by search robots and other machine processes
• Ready to receive styling instructions

In this last respect, you should be aware that most HTML elements can be styled to look pretty much anyway one wishes, but it’s not the text’s job to convey the styling. On the web, styling is the job of the language dedicated to that purpose: CSS.

HTML includes discrete elements for:

1. Headings (6 levels)
2. Paragraphs
3. Lists, and nested lists
4. Links
5. Emphasis and strong emphasis
6. Quoted text
7. Tables with columns and rows

Don’t make things worse with the wrong starting point

The way that Word encodes these elements is fundamentally different from HTML, incredibly verbose, and doesn’t even cover the whole semantic palette. And although Word provides a ‘Save As HTML’ option, the HTML created that way will make things worse.

Everything in Word gets styled to some degree, and the focus on appearance creates a mindset where it’s all too common to end up with:

• Headings that are just bold text
• Link text indicated with an underline with no link destination specified
• “Italics used to represent quoted text”
• Comments and instructional text that is just differently styled text within the stream of actual content, so it has to be stripped out.

These kind of outcomes are not fit for purpose.

Markdown to the rescue

Markdown syntax is a proxy for a focused subset of HTML that addresses the types of formatting mentioned above (plus a bit more). It has that focus because although HTML has over 100 elements to work with, the vast majority of web text content uses just the limited subset described above.

With Markdown, you write in a way that isn’t HTML, but the end result can be processed to become HTML — automatically.

Many Markdown processors will also take care of automatically finessing:

• Straight apostrophes, single quotation marks, and double quotation marks into their “curly equivalents”
• Double hyphens into — em-dashes

Crucially…

Markdown is a lot easier to learn, write and read than HTML

For example, in HTML you could write a link such as:

<a href=”https://en.wikipedia.org/wiki/Hyperlink>Hyperlink</a> 

In Markdown, the same thing is:

[Hyperlink](https://en.wikipedia.org/wiki/Hyperlink)

At first glance, that might not look a lot simpler, but let’s abstract it:

[Link text](url)

…and consider why that’s good:

• There is less to read
• No need to remember the correct HTML <tag> and its closing equivalent
• No need to remember the href attribute

And if you get it a bit wrong? Sure, you won’t get the desired outcome if you write: [Link text] (url) or [Link text][url], but at least the formatting won’t break, which it can with malformed HTML.

It’s essential to see your text’s semantics as you write and review it

In particular:

• Links are the glue of the web. Where a link goes to is vital. It’s not sufficient to underline some text to imply a link and then hand-wave 👋 about where it points to.
• Headings and their hierarchy are vital to the accessibility of your text. Look at the subheading above. Can you tell what heading level it is? If you were reading this in a Word document could you tell then? You might, if the author had used Word Styles diligently, but what if they had just made text bold and bigger?

The above sub-subheading should be level 3, because it heads up a sub-subsection of ‘Markdown to the rescue’, which is itself a subsection.

As it happens, Medium is terrible at observing heading semantics, and makes it a level 4 heading. But just because Medium and other places do things wrongly doesn’t mean you should contribute to making the web less accessible. Especially when it is really easy to do things the right way, with Markdown:

### It’s essential to see your text’s semantics as you write and review it

Those 3 leading hash characters (pounds if you are American) tell you easily and unambiguously that that text is intended as a level 3 heading.

You might think, “Who cares?”, but as Heydon Pickering rightly observes, it’s vital for some people, because:

“headings are infrastructure”.

Markdown is a format all modern CMS frameworks support

With the right configuration, you can paste Markdown formatted text right into your CMS field and it will get converted to clean HTML for output.

Ironically, you can’t do that here on Medium 🙄 — which is why Jake Bennett created a web app for that workflow.

Markdown is lightweight and portable

The source text for this article is just 4 kB. The Word equivalent is 26 kB. Not such a big deal one might think, but the Word version is full of crud your developers will have to fight against when it moves into production.

Consider also that Markdown is just plain text and that:

• Every Windows user has Notepad, and every Mac user has TextEdit.
• Not every Windows user has Word, and most Mac users don’t.

(And for Linux users, all this will not be news: they’ll have their own preferred Markdown savvy app already.)

Ultimately, the most important point is…

Writing in Markdown is an ideal environment to focus on structure and meaning, and disregard style.

The right Markdown app for the job

There are many great apps that are optimised for Markdown, which do things like:

• Provide formatting buttons to generate the right syntax so you don’t have to remember it.
• Subtly render text in a manner sympathetic to the intent so it is easier to read. For example, rendering a link URL in lighter text so that the focus is on the link text but its destination is still visible.
• Provide a preview mode that mimics a default browser rendering of your text.
• Provide options to export to .html, .pdf, and (when you have to) .docx.

There are lots of good guides to Markdown apps. Amelia Garvey wrote one for Shopify: The 10 Best Markdown Editors of 2018.

Importantly, because of Markdown’s portability, it doesn’t matter if you use one Markdown app and your colleagues on the same project use another.

Collaborating and tracking changes

This is an area of weakness. Not of Markdown itself, which was never created to address collaboration or version control. But it is a challenge for the Markdown ecosystem.

Editorially was the best Markdown oriented interface I’ve ever encountered, and had this base covered — far better than Word’s Track Changes — but sadly it couldn’t be sustained.

There are some good solutions to collaborating and version control. Probably the best that I’m aware of is Draft. On the more geeky side, you can roll your own solution using:

• Git version control
• Toolsets like CriticMarkup

Focus on crafting stylish writing, not styled words

In closing, do you want to write in a manner that fits the workflow?

If you do, your web and app developers will thank you and your publishing workflow will be smoother and more efficient.

Don’t be the spanner in the works. Go learn Markdown.