Markdown is Not the Right Choice for Technical Writing

Markdown is the nearly ubiquitous writing format in software development, supported by virtually every service that you’re likely to use. Who doesn’t write their GitHub README files with it?!

Markdown’s easy to write in, with the basic syntax being masterable in about 30 minutes, and the extended syntax in, perhaps, a few hours.

But, that doesn’t mean Markdown’s the right format — especially for all of your technical documentation.

Sure, it’s fine for simple content needs. Using it makes it trivial to formatting headers, bold, italicise, add lists, and add inline or larger code blocks — all of the things that you’re going to need a lot of the time.

But, it’s the wrong choice!

Why? Well, let’s consider a few key points:

Which flavour of Markdown does your platform or tool support? That might sound odd to ask. But there are seven major flavours. Then there are a platform or tool’s Markdown extensions to expand the underlying Markdown flavour’s capabilities (because, again, Markdown has a limited capability set). They won’t always be available as and when you migrate away.

Then, there’s the fact that, if Markdown doesn’t support some formatting aspect that you need, at some point in time, such as cross references, sidebars, footnotes, includes, and substitutions, you’re free to directly insert HTML.

But, does it make sense to insert HTML directly — when you’re using a simple formatting language to avoid doing that in the first place?

I doubt it.

Rather, it’s better to use a more sophisticated format, one that has all of the functionality you’re likely ever to need, one that is just as simple to use as Markdown, one that can grow with you over time.

This isn’t a pipe dream.

Two such formats already exist: reStructuredText and my favourite: AsciiDoc.

They’re worth considering!

Matthew