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.