Everything in that article is why I don't like asciidoc. I think a lot of documentation should be absolute dead simple - no macros and complex behavior. It should just work. Markdown is great for that.
I wrote a couple of books in asciidoc. MD might work for a web comment but if you want to write something sophisticated like a book you need more. E.g.
TIP: my tip
Super helpful when you're writing a book. My blog provider uses MD and I no longer have these handy popups or cool sidebars. I won't even get into tables etc.
Include is a bit problematic but having a way to have 1 chapter = 1 file is wonderful. You can then package the whole book with a file that lists the includes. Very convenient.
I've written a ~300 page book in MD using book-template [1], and I must say, it was a wonderful experience. I did 1 chapter = 1 file. It had tables, images, etc with a nice TOC along with references and appendix. All the basics for writing a book work just fine with md, I'd say. Here is the output (in pdf, epub, html) for you to judge [2]
This statement is case in point that most documentation is dirt simple.
On the other hand, if you're documenting an end product with complex print output, hundreds of (slightly) different configurations, and need transclusion, partial transclusion, conditionals - to say nothing of wacky tables and olists- you end up with a giant pile of Markdown customization. It's easier to just use Asciidoc off the shelf, not to mention that you get DocBook interoperability, which lets you transform to all sorts of weird old formats.
But that complex use case often comes with dollars attached for big proprietary solutions. Asciidoc is a an open standard in a space that usually has vendor solutions.
You get links, if you need more than that you're probably overcomplicating your documentation. Transclusion might sound nice, but now your docs have depedencies and they become harder to send, harder to host, and harder to edit (is this edit in this transcluded file going to work for every other file that includes it?). Then someone goes "I use it for templating" and now you have a CMS. It's a slippery slop that markdown sidesteps by going "no. You get links. If you need more than links, you're probably overcomplicating your documentation".
I find this view a bit simplistic. As a reader I find it much easier to follow if I don't have to piece information together from different documents. Including relevant sections in the correct place will improve the flow of the text a lot.
I think the bigger downside is that the include directive doesn't really help you when you're reading the source file, but markdown was explicitly designed to also be pleasant to read "raw". Realistically however, you will render you docs into HTML (or pdf) so that doesn't really matter.
I also find includes neat to include code snippets from separate files, so I can run linting and other checks on them independently (and sometimes even run scripts as independent files).
That, honestly, feels like a problem with the markdown reader, not the format itself. A problem common to modern browsers, but also prevalent in many doc readers: Much like how a good code editor can show you "the thing you need to resolve" inline (e.g. looking up the definition of a function you highlighted), a good markdown reader should be able to trigger what looks like a transclusion in the document you're reading when you click a link, in addition to the normal link resolution.
Hmm, but you will probably like to link to something, right? Do you just put links in your Markdown? Do you link to markdown files an post-process when rendering to HTML (or maybe you don't render it at all)?
