Don’t Use Markdown for Documentation (2016)

Articles like this come up every so often, and they usually point to all the problems with Markdown -- slightly incompatible implementations, nonstandard extensions, how difficult it is to correctly parse in all cases, how mixing non-tag markup and HTML offends proper sensibilities, etc. And I can't say that they're wrong, per se. Markdown is a terrific example of "worse is better."

That's the thing, though -- the whole argument for "worse is better" is that it produces more successful software. In practice, it turns out that it's pretty easy for most people to write most things in Markdown, no matter which processor they're using, just merrily mixing in HTML (or template tags) when they need to. The arguments for AsciiDoc and ReStructuredText usually boil down to "they make difficult things easier," which they do -- but they tend to make more common things (links, images, blockquotes, footnotes [not technically "standard" Markdown but the [^fn] notation is nearly universal]) a little more difficult. Markdown, by contrast, makes the things you're typing all the time trivial, while still letting you do anything that you can do in HTML by, well, letting you do it in HTML.

The litany of issues about Markdown flavors and interop issues there doesn’t ring true to me: most tools these days use Github-flavored Markdown. Never had a parsing problem between the various Ruby, Python, and C markdown libs I’ve used over the years.

Getting engineers to contribute to docs is hard enough; it’d be quite a barrier in my org to also teach them a new markup language. Everyone already knows Markdown or some subset of HTML.

While I understand the point that the article is trying to make, i.e. that no "standard" markdown offers sufficient features to write documentation, I don't think that it matters too much as long as the final result is good.

I always wanted to write manuals and documentation in markdown (or any other lightweight markup language for the matter) but not even a specialized flavor of markdown was able to provide all the features that a technical writer expects from a documentation tools (I am talking especially about block-level formatting and content reuse).

So I came up with HastyScribe (https://h3rald.com/hastyscribe/) and then HastySite (https://h3rald.com/hastysite/).

Basically, I used Discount as a base and added features on top of it. I am now using it for all my sites and all the documentation of my open source projects. And I know of at least one company that is using HastyScribe for their own user documentation.

OK, there's some degree of vendor lock-in, but at least the final result is OK and both tools are open source.

For more info and a preview of what an HastyScribe document looks like, here's the user guide:

https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm

Since most people commenting will do so without even opening, let alone reading, the linked article, let me draw your attention to the last line:

>Full Disclosure: I work on a product, Read the Docs, which is based on Sphinx, so my views are likely biased.

If I can anyone to actually write documentation, I don’t care what tool they use as long as it’s a reasonably accepted tool.

Any flavor of markdown qualifies.

What we ended up doing was just reusing our existing bbcode support. Markdown wasn't giving us anything over it really and it was easier to reason with, especially for non-technical folks and translators. We were able to extend it for our use cases much easier.

All of this after the initial plan was to use Markdown.

Rust seems to disagree, and I'm glad of it. Documentation is easy to write, and reasonably extensible. Sure there are things I wish to see added (LaTeX math mode would be awesome) but there's nothing really stopping this from happening, even if it's not part of a universal standard.

Markdown is fine for small snippets, READMEs, Github comments etc., but I don't think it's suitable for a longer document such as software documentation. After thinking about that problem and exploring options for a while I have come to believe that some lightweight markup that can be converted to DocBook may be the way to go. I have blogged about such a pipeline here: https://nablux.net/tgp/weblog/2017/04/02/lightweight-semanti...

Thanks for the alternate suggestions (biased as they may be).

My biggest pain point when writing doc in md is tables. They are so hard to parse in the raw text, and I constantly have to be checking the rendered output to make any edits/find my place.

Does anyone know of a good alternative to md (including Sphinx and Asciidoctor) that deals with tables better?

Discussed at the time: https://news.ycombinator.com/item?id=11292280.

The alternatives mention python and ruby. What drew me to markdown in the first place was the absence of dependencies.

only if github offered sphinx support.