Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

Here. Let me tell you a story.

Some years ago, Leadership in decided to stop paying for the S1000D[1] software. This would make the publications group effectively homeless. The objective of this tactic was to force a move to the PDM system's tech writing system, which had previously been rejected by more or less everyone.

I put out a plan[2] to keep the S1000D architecture (filenames, books, links, etc) but use lightweight markup and open standards from the programming industry, to do the actual writing. Which lightweight markup language? I needed the following:

* Transclusion, need to bring in files (data modules) from a centralized publication module

* Partial Transclusion, need to be able to bring in part of another file, what would be called CIRs in S1000D

* Conditional content, usable inline, so that a step or a figure could be toggled on and off depending on a condition set in the Publication Module. This emulates Applicability in S1000D.

* Complex print output

* Nice-to-haves: an AST that maps to a legacy format aka DocBook/DITA/S1000D/MIL-STD-38784/etc; publishing pipelines capable of weird crap like complex front matter, TOC, indices, header/footer/margin running content; a singular standard that had some life in it

I took pretty much every lightweight markup variant out for a spin with a test migration and publish, on my own time, nights and weekends. I found that there was a Markdown variant that could almost do everything I wanted, but it had a dependency on a document processor. ReST functionality similarly depended on notebooks and Sphinx. LaTeX HTML pipelines were a bit janky and hard to set up on Windows. Neither really tied to a legacy XML format, which limited round-tripping with something as insane as S1000D. And the print options for both ReST and MD were not where I needed them, particularly for tables, but also for running content. Asciidoc came the closest to checking off all the boxes for me.

Anyway, it happened, it worked, I did it. But it hit business process problems. Stuff that would have hit any new instance of a pubs too. Like "we don't actually know which plane parts can work with each other" or "SMEs will never ever ever do a review in a text editor . . or electronically . . or in anything but a dead tree" or "a few writers don't know what the scroll wheel on the mouse does"[3] or . . eh, take your pick. I ate my own gun, though, and left. They're still using it - and probably still cursing my name - to this day. But that had been one of my big goals[4]: S1000D architecture on lightweight markup.

So. Lightweight markup. I haven't continued to shop around, and I probably should. For one, I'm of the growing opinion that inline conditional content is a mistake as a general design, and that the conditionals should probably live in the processing layer. That's a big chunk of the requirement covered by Asciidoc's `include` directive. For another, I won't deny that the Markdown ecosystem is about 100x the Asciidoc ecosystem, due to the much greater dev count with the JS ecosystem vs the Ruby ecosystem. Some of the toys in Markdownland are worth the move all by themselves. And round tripping S1000D? You can't even round trip S1000D with itself.

Then again, there's so many damn MD variants. .

[1] XML vocabulary for documentation of mil/aero systems. Think DITA but a million times more complicated. And a new Issue every two years, without any commonality in the scope.

[2] This was a mistake, as I made lasting enemies of the PDM boosters, who counted some executives among them. I would have been better off keeping my mouth shut and letting the whole thing sink into the ocean.

[3] And had no interest in finding out, either. "You're trying to turn us into programmers, with this git and text stuff!". No, no I am not, and if you ever want to work outside this sector you'll want to learn what git is.

[4] Should probably mention that annual per seat license costs for the big S100D solutions were pushing past 30k, with reviewer licenses lagging not far behind that. Not including the setup costs, or the consultants that will have to fly down for every tweak and button. I could not, for the life of me, figure out how anyone manages to pay for that in avionics, where the margins are razor thin. Turns out they don't, they just deeply discount their products so the OEM can "show them how it's done". Effectively they're paying their suppliers with dollars that can only be spent with the OEM.

What I like is how easy it is to host MkDocs on GitHub Pages via built-in support, but you can even make it behave like Jekyll with GitHub Actions. Shameless self-plug of another blog post: https://gaseri.org/en/blog/2022-11-01-publishing-material-fo...

This is my beef with Markdown. Automatically numbered lists always break for me--every time. And Markdown doesn't support decimal numbered lists (1, 2, 2.1, 2.2).

I can ignore spacing, because every markdown has bad spacing (space before and after a formatted block or header or list), but I loath the inflexibility of numbered lists.

That said, for my projects I use Markdown, because its so simple--necessary and (mostly) sufficient.