A subject very near and dear to my heart. Asciidoc, flawed as it is, is still the best game in town, with conditional content, transclusion, and a particularly

A subject very near and dear to my heart. Asciidoc, flawed as it is, is still the best game in town, with conditional content, transclusion, and a particularly robust table model. Combined with S1000D architecture, it makes a passable method of writing publications for heavy industry in aerospace and defense. On the double cheap. If your team has some small amount of tech chops. The `include` is a problem, though, and the devs have known this since at least 2017. Two directives under work here. The `ainclude` is an extension that works in the subdoc direction, and `subdoc` is a directive under development that's on the milestones to go into core. Generic blocks is also on the roadmap, and it's available via extension. However. There's deeper problems, I feel, inherent in the DNA of component content systems themselves, as a basic concept. It plagues every CCMS (component content management system), whether it's DITA, S1000D, DocBook (with xincludes), ReST, or otherwise. It's not a markup problem. In S1000D, I call it "the applicability trap". To put this very briefly, you incur risk when you replace any component of natural language with a constructed language. In the case of CCMSs, you have an implied content architecture doing the work of NL in between content "chunks", but not everyone architects content, or, hell, even their product. The writers won't know this until they start, and by then it's too late. Without architecture, you have a bunch of chunks that used to be structured linguistically, and now they're not doing much of anything at all. I can't tell you how many S1000D systems I've seen built around a product that existed as little more than a twinkle in a salesman's eye. You build out an SNS and an applicability model[1], all from a bunch of emails or a spotty CAD diagram, and tell the writers to get cracking. Then, N months and N millions of dollars later, scrap everything because, lo and behold, the actual possible product completely invalidates the content architecture. "How did the doc set cost 19 million dollars?". Well, it's not the markup, it's not the vendor, and whatever miracle editor your salesmen buddies are pushing won't do jack to fix it, either. What the writers need is a quantifiable test for architecture before they start, or else, sooner or later, the Applicability Trap will get them. Either that, or write individual BDMs[2] for every single product variant that spews out of the pieholes of business development. I feel a little dumb getting worked up here. All of this crap is going to be glitter in the river come 2030 anyway, because we'll be training our pocket AIs for most of this. [1](sort of a structure of conditions to filter content) [2] Big Dumb Manuals, like mamma used to make