Posted this because I started exploring Asciidoc recently as a medium for documentation. Here’s a link for the last time this was posted:<p><a href="https://news.ycombinator.com/item?id=11292280" rel="nofollow">https://news.ycombinator.com/item?id=11292280</a><p>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.
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.
> Once you start using markdown flavors, which is required for any non-trivial documentation, you lose all portability benefits.<p>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!!"<p>Except people almost never change databases. I shouldn't think people change their documentation formats either.