Why You Shouldn’t Use “Markdown” for Documentation
ericholscher.com
ericholscher.com
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.
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.