Why I use Markdown for Documentation

This post is in response to an article from last week - Why You Shouldn’t Use “Markdown” for Documentation.

I use Markdown daily for working with project documentation. Django REST framework is the largest project I use it for, where we use Markdown and MkDocs. We're perfectly happy with our tooling choice there, and have no intention of switching anytime soon.

In fact, I deliberately ported Django REST framework over from reStructuredText a few years ago, specifically because I found working with documentation in Markdown to be a more pleasant experience.

The readability, tooling and adoption aspects of Markdown are huge wins. In my judgment they are substantial enough to outweigh other considerations for my project documentation right now.

Readability

This is subjective of course, but Markdown is generally a pretty nice, simple and readable format. I personally find it pretty pleasant to read through, and I believe that's been reflected in its wide adoption.

No tool is perfect, in particular image links in Markdown could be a little more graceful, but everything else feels natural and intuitive. The language is also reasonably constrained, meaning there's not too much to learn.

Adoption & Tooling

Markdown has a far greater adoption than any other markup language. That means it's easier for others to contribute to our documentation. As a result of this adoption, there are also a huge range of really great markdown editors available. Being able to work in a decent editor helps me to visualize the layout and flow of the documentation.

Presentation

Markdown is not a general purpose markup language, but rather is designed specifically as a text-to-HTML tool. That's just fine for my purposes.

On occasion I also need to embed HTML directly into documentation for index pages or announcements where presentation is key. There's a trade-off here of course - if you embed HTML directly then you're losing readability. However for a limited set of cases where I really need to control the page display, it becomes invaluable.

Addressing the criticisms

The arguments presented against using Markdown for documentation don't particularly resonate with me.

In practice it's not an issue that Markdown is informally specified. I've never had issues with editors or tooling displaying my documentation in different or inconsistent ways.

I've no great issue with tooling that supports either regular Markdown, or elements of GitHub flavored Markdown (tables, strikethrough, and syntax highlighting.) In my view none of the other 'flavors' have enough adoption to be treated as anything other than esoteric implementations.

I actually don't want my documentation markup language to support custom extensions. They add flexibility but typically introduce dependance on a particular programming language for tooling, and make documents less universal.

I also don't need my documentation markdown language to provide for semantic meaning. What I need is a readable format that is designed specifically for rendering to HTML. It's true that Markdown isn't designed for generating multiple differing output formats, but I don't particularly care if my documentation supports PDF output or not, and personally consider that a fringe benefit.

Summary

No tool is perfect, and we should avoid getting personally invested in our tooling choices - I wouldn't lose any sleep if I had to switch to AsciiDoc or reStructuredText tomorrow, although I'd prefer not to.

I'd also welcome a nicer way of interlinking within documents, which Markdown doesn't support. I have some thoughts about how this could be addressed without needing to extend the language, but I'll leave that conversation for another day.

Right now I'm sticking with Markdown. Not because it's a lowest common denominator, but because for myself, on a day-to-day basis, it's the best tool for the job.

DabApps offers technical consultancy, as well as bespoke development services. To find out more, get in touch. You can also follow Tom on Twitter.