| Comparing AsciiDoc to Markdown (instead of for instance reSructured Text/reST) is clever, but I don't think there's any widespread controversy about the shortcomings of Markdown. So that's just an easy win. I've seen this premise a lot (quoting from the article) »The most compelling reason to choose a lightweight markup language for writing is to minimize the number of technical concepts an author must grasp in order to be immediately productive.« What relevant documentation markup languages have this issue? If we already agree that documentation should be written as code, let's embrace it and not be scared of showing syntax. It's our tools that matter here - syntax highlighting, previewing, CI feedback. I see much more that people writing markup languages get extremely motivated from their first victories with coding something. Don't be afraid of showing people syntax -- Wikipedia got pretty far with a less-than-optimal markup language! I think the real issue with AsciiDoc is something more along these lines: https://xkcd.com/927/ I'm working in a large organization where we are failing to streamline and spread documentation practices because of many different standards and practices popping up everywhere. I like a lot how the Python community has centered around Sphinx and Read the Docs. It's great that for instance Sphinx support both Markdown and reST in that regards -- but then when things like Hugo/Docsy, AsciiDoc, Github Wikis, groovydoc etc. starts popping up, the unification of documentation practices in a large organization becomes harder -- and also of course across the specter of Open Source projects. |