I love writing documentation in asciidoc (using asciidoctor actually). However I keep running into certain issues. For example, if a document includes pictures, and the file path has spaces in it, then you have issues. I believe you can replace spaces using HTML escapes if your output doc is HTML, however that falls apart if you want to make a PDF from the same source.
I'm also still trying to wrap my head around the presentation side. You can use something like style sheets, but it doesn't look like the same style sheets are compatible with both HTML and PDF output (if memory serves). And if you want to output to docx format, you can do it, but again the output looks different.
Another downside is that rendering larger documents to PDF will become incredibly slow. We have documented a REST API with AsciiDoc via Spring RestDocs and the build takes like 10 minutes for the PDF only. That doesn't include generating the snippets with RestDocs, which is rather fast. I suspect it has to do with AsciiDoctor being written in Ruby.
I'm also still trying to wrap my head around the presentation side. You can use something like style sheets, but it doesn't look like the same style sheets are compatible with both HTML and PDF output (if memory serves). And if you want to output to docx format, you can do it, but again the output looks different.