| “it also fulfills the objective of ensuring your content is maximally reusable” This is a bit of a trap when it comes to teams chasing the goal of modular documentation. AsciiDoc let’s you include other AsciiDoc files, so teams modularize content with the idea that all these modules are potentially reusable. But unlike code which, say, might use a method that is available bc another file has been included/imported, an AsciiDoc include doesn’t reveal any of its content. It’s just a file name that will be replaced with the content of that file upon render. This means you literally cannot read modularized content from source - you need to open up every included file and read each out of context. Available tooling also presents previewed/rendered includes as if they are part of the parent document, which removes the ability to identify modularized content from the output. In my experience this results in documentation that is modularized by diktat - usually after being authored in a Google Doc. Reuse never happens, in fact nobody but the author really knows what content was modularized in the first place. |
Which is 100% nuclear stupid, because, as you point out, you can't do component content without conditional content. And once you start doing conditional content, you need to have a damn good idea of what your whole product architecture looks like: what works with what, which packages are packages, obsolescence, blah blah blabbity blah. At industry conferences this makes me mad enough to spit, and all those goobers are suckering these writer teams into paying $7000 per person per (EDIT)month (!!) for a system that's going to be nothing but heartache in thirty six months.
Luckily, Asciidoc does have conditional directives, but the include directive is wayyyyy too primitive for what it's being used for right now (also as you point out). The `ainclude` directive is in extension right now, and it will probably be brought into core as a subdoc directive.
Having said that, it really is the best game in town, for generating both modern HTML alongside old-timey PDFs and DocBook XML, all from the same source.