4 ms·
Why You Shouldn’t Use “Markdown” for Documentation
- Cieplak 8y agoPosted 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 8y agoToC and links to headers that give warnings when they break. Can't live without it :-)
- kstenerud 8y agoPeople 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 8y ago> 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.
- deleted 8y ago[deleted]