
Why You Shouldn’t Use “Markdown” for Documentation - Cieplak
http://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
======
Cieplak
Posted this because I started exploring Asciidoc recently as a medium for
documentation. Here’s a link for the last time this was posted:

[https://news.ycombinator.com/item?id=11292280](https://news.ycombinator.com/item?id=11292280)

Markdown is incredible and probably the best tool for writing simple
documentation. I started using asciidoc recently due to its native support for
table of contents, links and the excellent support for tables. Was inspired by
Ciro Santilli’s use of asciidoc for his documentation projects. Ultimately
tools are tools and nothing is perfect, but hope that this might also inspire
people to increase their documentation game.

~~~
cirosantilli
ToC and links to headers that give warnings when they break. Can't live
without it :-)

------
kstenerud
People use markdown for documentation because it's usually good enough. Every
reason in this article doesn't matter to the guy making readmes or blog posts
or most things under 1000 words. And most things people write are under 1000
words.

------
zimpenfish
> Once you start using markdown flavors, which is required for any non-trivial
> documentation, you lose all portability benefits.

This is the same argument people use for ORMs over bare SQL - "what if we
change database later, we'll have to do lots of rewriting of queries!!"

Except people almost never change databases. I shouldn't think people change
their documentation formats either.

