Don’t Use Markdown for Documentation (opens in new tab)

I wrote a six book, 1100 page series in Markdown (all on github). I write all my blog posts in Markdown.

I'm sorry but I just can't sympathize with any of the complaints leveled against Markdown. They are so minor and compared to the massive adoption of the common bits of Markdown, there's no chance I'd ever choose to write anything in any other markup than that just for those small annoyances.

I don't need custom extensibility when I can just add HTML. HTML is pretty good at markup, and it enhances the markdown in those rare occasions where what's provided seems too limited. The very last thing I'd want to do is literally write code as an extension to my markup language. The only code in my markdown is inside nice tidy code blocks for display purposes only.

I also use JSON for configuration, even though many have tried to convince the community that YAML or some other format is better. I pre-process my JSON to strip it of "non standard" comments, and I'm quite happy that I chose the by-far-defacto-standard there instead of going off the beaten path.

After having written a fairly popular 400+ page book, and dozens of documentation sets in Markdown (and having worked on a few in other languages), I have to say—Markdown is _good enough_.

The other syntaxes mentioned will not be mainstream enough to gain critical mass for some time, if at all. Markdown, for many projects, is literally plain text with some added frills for headings, lists, and code blocks.

Yes, adding a code snippet inside a table cell inside a list can be a pain-inducing experience (especially until CommonMark settles things down a bit)... but that's about .05% of anything I've ever written, and for those particular instances, I fall back to HTML, which is completely compliant and much less ambiguous.

For myself, and for most of the projects I've worked with and maintained, you need documentation to be dead simple in syntax, and requiring a syntax with even less adoption than Markdown is an easy way to cause users who would've otherwise contributed doc fixes and updates behind.

I love Markdown. I enjoy RST. I think, like programming, they have their own merits and use cases.

Markdown is a lot less verbose in my opinion than RST. It's not intentional, nor is it insurmountable, but little things like inline code, hyperlinks, defined subsection levels, and many more all add up to a bit of cognitive load that I don't need for all situations. When I'm writing quick notes for a meeting, or trying to jot down something, RST is a bit much. Which perhaps isn't what this article is really harping on.

But when my quick notes to myself about a project turn long-winded and become more of functional docs, it can be a pain to rewrite that into rst.

I do, however, tend to use RST when I sit down to write documentation for a project. I even tend to use it when documenting firmware and hardware portions of projects. This of course due to the so far poor handling of images in Markdown.

So like I said above, they are tools. One may be better suited to something than the other. But thus is the nature of tools. Use the right tool for the right job whenever possible.

And then there's CommonMark: http://commonmark.org/

They aim to standardize the "markdown-like" formats into a single unified one. It's not done yet but it's certainly better than everyone for themselves.

Markdown has a lot of faults, but it solves the one single biggest problem in writing documentation that basically overrides every single other consideration: getting people to actually write it. Basically nothing else matters except this.

And I disagree about the portability. Write Pandoc-compatible markdown and you can convert it to just about any format under the planet. I love that I can write in Markdown, then quickly create a word document to send around the office for comments - whatever anybody says about Word, the track changes and review functions both useful and defacto standards in most offices.

Markdown is wildly popular because Markdown is easy to write and read unprocessed. At a basic level, it's little more a few conventions for writing text.

RST, used by Sphinx, isn't quite as easy to write or to read. There are plenty of gotchas. RST adds friction.

Using Sphinx also requires you to setup and configure Sphinx for your project - even more friction early on.

The world is far better for having Markdown, and it's the right choice for most projects.

However, there is indeed a place for more complicated projects to take on the workload of a more complicated documentation system so that they can help user and developers better. Django's amazing documentation is an example of this, and a major reason for the success of the project.

I feel like this drive to use a document description language that is "natural to read in ascii" but also works as a real markup language ends up fulfilling neither in practice. I prefer LaTeX than any of these half-assed markup languages that never quite works as you want.

The primary limitation I've found with Markdown, and the one reason I revert to LaTeX for longer documents, is the lack of support for equations. I'd love to be able to just add LaTeX math between dollar signs.

Is it [text](URL) or [URL](text) or (text)[URL] or...? It's impossible to remember, because this syntax is bizarre.

Rust uses markdown (with some extensions) for its documentation. This has some limitations, and there was a discussion [1] about changing this to RST a while ago, but it never happened.

[1]: https://internals.rust-lang.org/t/rustdoc-restructuredtext-v...

Ah. This reminds me of a great discussion that happened over at the Rust Internals forum about which markup language to use for documentation. [0]

tl;dr: Markdown won.

[0]: https://internals.rust-lang.org/t/rustdoc-restructuredtext-v...

The fundamental complaint seems to be that the portable subset of Markdown doesn't allow for extending with new types of blocks.

I find this an unconvincing argument against Markdown per se. It's an argument against writing in the portable subset of Markdown, but why would anyone need to do that in their documentation? It isn't as if specific Markdown implementations are hard to come by, or that there is a context where it would be onerously hard to mandate a specific implementation.

Not to say that Markdown's fragmentation isn't a bad thing. It's annoying, especially when you do use different implementations in different pieces of software and you're trying to remember whether this version supports tables, say, and what the syntax might be.

> “Markdown” is the most commonly used markup language on the internet.

That'll be HTML. :) Not just being facetious. HTML is certainly an option for documentation, albeit not one I'd be totally happy with.

> You also can’t migrate Markdown easily to another markup language (Asciidoc or RST), because Pandoc and other conversion tools won’t support your flavor’s extensions.

Unless those flavours are Markdown Extra or Github or CommonMark, which pandoc does support. Pandoc also supports adding specific syntax extensions ad-hoc, as noted in its fine documentation. Although, I'd question why this would be an issue in practical terms.

Personally I love how in Elixir, documentation comments are markdown. The Elixir runtime even comes with a nice tool that generates awesome HTML from it.

For example, this:

https://github.com/parroty/extwitter/blob/master/lib/extwitt...

Becomes this:

https://hexdocs.pm/extwitter/ExTwitter.html#follow/1

> “Markdown” is the most commonly used markup language on the internet.

Wouldn't that be HTML? :)

If you're using Github and/or Pandoc for things, you can pretty much drop org-mode in as a replacement. It doesn't even require emacs :-)

In general, I find org-mode about as easy as Markdown, but with support for things like cross-references that are sadly lacking in standard Markdown.

I don't have a particularly strong opinion about most markup, but I know for sure I'll never use something that uses xmlto/xsltproc as part of the toolchain (such as Docbook). As a maintainer of several packages for a Linux distribution, I've gotten far too many headaches dealing with packages that rely on Docbook for generating their manpages or other documentation. The user's xsltproc setup has to be just right for the packages to build. Anything off in the XML catalog will break the whole build. Supporting it has been the opposite of fun.

For manpages, I write mdoc directly. It's not hard. There are several great mdoc resources on http://bsd.lv

For reference material, I stick with either Pandoc or I use LaTeX (along with tex2page for generating HTML). Anything fairly small tends to get the Markdown treatment. If it's something I foresee will need to be split into multiple documents, I reach for LaTeX. Scribble is pretty nice, too, if you're dealing with Racket or Scheme.

Yep, I tend to agree with the author. For software documentation with complex APIs, something more robust than markdown is necessary. For the same reason that writing extensive in-line HTML+CSS markup is bad, relying too heavily on HTML as the "fallback" for styling and structuring things that markdown cannot handle is just not efficient.

Here's a quick cheat sheet... for the "why" of semantic styling your docs with something like .rst with directives makes for better overall integration.

https://github.com/indie/sphinx-deco/blob/master/sphinx_deco...

Getting developers to write documentation is hard enough already.

Raising the barrier to entry to include learning complicated markup languages will chase them off completely.

I agree, it's far from perfect. But some documentation is better than none.

TIL that Read The Docs is a product and not just a condescendingly-named website with mirrors of python docs. :)

I really tried to write in ReST but there is nothing intuitive about the syntax and I kept forgetting how to do things, it also makes the plain text unnecessarily verbose and does not support simple things like combining styles (i.e. good luck if you want something be monospaced AND bold without terrible kludges).

In the end I converted to Asciidoc, it does all I need, is readable and is not as python-centric as docutils (I use the python implementation but asciidoctor is ruby and there's even a chrome extension for live preview in the browser).

I think most the arguments made in the piece don't matter but the argument for Lack of Semantic Meaning is interesting in how Markdown solves it. First off the argument is bad because Markdown can have semantic meaning, it is just defined with HTML. So the real argument is semantic meaning in HTML sucks. In his example, I would generally agree. However, what if you just used <warning>Warn Me</warning>. I kind of like that a lot.

I guess markdown is nice for unstructured text.

When you think you can learn a job (technical writer) by doing it bad rather than not doing it at all, you just take bad habits.

Serious technical documentation are structured. Pictures have captions, graphs have legends... It is cumbersome, it requires more data but that is the price to communicate (wait for it) INFORMATION to other humans.

Yes, writing structured documentation that can be easily used is part of what information technologies are. Structuring information from data.

Information is still analogic at the end and rst is just a typesetting chain designed for a domain specific kind of documents called technical documentation.

I am totally biased. I love readthedocs, I love POD, man pages, ISO documentations, IETF RFC, ASM papers, all kind of scientific papers, useful instructions that can help me do my job faster by following well known practices to be consistently readable without strain. And rst for this level of requirement is less a PITA than doing it conscientiously by hand or with markdown.

But I agree, I totally love the artistic freedom of markdown for writings too. But in a Museum, or as grafitis.

We talk about documentations right? Not art? So the title is accurate.

Agreed. Better use docx for every type of documentation. Just embed it with base64 if thats what you need. Nothing more standard than a good ol' docx.

"portable if you install all the custom extensions the document needs" is a fairly poor implementation of "portable". You might as well call the different flavors of Markdown "portable" (contra the article) since all you need to do to render them correctly is install the right parser...

Don't blindly follow advice from articles with hard "yes/no" imperatives as titles.

I have been expecting github markdown to become the defacto standard just as github itself has become the defacto standard for hosting.

This would be a good thing since any standard is better than the tower of babel we have now.

Rst is a bit harder to write but more powerful and extensible. To alleviate some of the syntax annoyances I created some snippets in my editor.

> This leads people to embed HTML directly in their Markdown

I don't find that too bad.

that's like... your opinion, man

I have done just fine with md

Wah wah. I disagree. I'm tired of seeing this in Enterprise:

* 100 page Word document. 200 page Word document. Take your pick.

* 99% of it is clearly cut and pasted from somewhere else and contains information absolutely incorrect and irrelevant to the task at hand because it was accidentally included from the last document they cut and paste from, but people are afraid to remove it.

* Someone has manually typed in a few lines into a table (oooh, so THAT'S the temporary IP address of the server which will almost certainly change at a later date!) As it's buried in the document there's no way to extract, verify, or update it. It will be listed with a bunch of other IP addresses from the prior cut and paste, and if you get a server name in there, it's probably wrong too.

* They've also handed off the effort to any Architect, probably one of the people I see sitting in Visio day in day out drawing those diagrams of how a computer connects to the network. In a VM data centre. Where it's meaningless and has no connection to reality. And where the moment it gets turned on someone will install software that connects to 20 other servers in ways that will never be described let alone in this document let alone in a diagram.

* Now, take that, cut and paste the whole thing keeping it 90% intact, call it a "Controlled Document", add in the names of some people at the front and last edit dates (where every document starts at version 0.1 and stays there for its entire lifetime), and now you've got a process manual! Hundreds of them! Thousands of them! Don't worry they were all based on whatever kind of template the business was branded with from year to year so you can kind of tell which decade they were first created.

* And they'll be dumped in shares because whatever multi-million dollar document management system was never used by users before being bought and never ever ever works. If you're lucky they might have version numbers or edit dates which don't correspond internally but get you 90% of the way to finding which one is current.

I get to see those holy manuals in Enterprise every day. You have no idea how bad it is.

Pick a third party format apart from Markdown? Are you fucking serious? Enterprise doesn't buy fucking third party software and everything is locked down so that you can't run your own. This is Windows for fuck's sake and there aren't even decent free Markdown editors for it anyway.

I write MY personal documentation in Markdown and I do it in a plain text editor. If I ever need to draw a diagram or put in a picture then I know I've fucked up and to backtrack. It's just plain text. That's what Markdown is for. "Not portable" my arse. About the only thing I wish was easier is tables. And they'd probably be ASCII tables at that.

So yeah. The argument against Markdown is bullshit.

Markdown is a virus. The virus shows you how you don't need markup at all.

Markdown actually works great for documentation.

stick a certain version and do not change it.

the article is likely bias as writes states he works for read the docs.

This is what I think of when reading this article: https://xkcd.com/927/

=================================

Situation: There are 14 competing standards

"14?! Ridiculous! We need to develop one universal standard that covers everyone's use cases.!"

"Yeah!"

Situation: There are 15 competing standards

==========================

The argument is that there are too many variations markdowns. Their solution? Another markdown.