Choosing Asciidoc After Two Decades of Trial and Error

We did not begin with AsciiDoc. We began where most teams start, in Word. It gave us quick wins like immediate formatting, tracked changes that non technical stakeholders understood, and a low barrier to entry for subject matter experts. It failed the moment documents became manuals with variations. Styles drifted across files, cross references broke during edits, and every export to PDF became a manual ritual. Producing two consistent outputs, web and PDF, was unreliable and slow. Long documents were also harder to version, and diff reviews focused on layout noise instead of substance.

Next up was LaTeX, which we used for Merlin 2. We respected its typesetting quality and the control it offers over layout. For a thesis or a single book, LaTeX shines. For a living documentation set with frequent updates, non technical reviewers, and a need for fast HTML alongside branded PDF, it slowed us down. Authors who were comfortable in text had to spend time on layout quirks. Reviewers could not easily preview the exact output without a build step, and small edits sometimes spiraled into formatting fixes. LaTeX rewarded experts but raised the floor too high for everyone else who needed to jump in quickly. We even had a teammate who promised a banger documentation in LaTeX and delivered exactly that. It was excellent. Then he left. No one wanted to take over the toolchain and the little fixes that kept it humming. The docs started to fall behind, and over time they deteriorated.

We tried Markdown next. We liked the simplicity and the fact that developers could contribute in plain text with clean diffs. For short guides this was perfect. As requirements grew, we needed tables with real structure, stable cross references, callouts, and a way to reuse content across versions. PDF in particular was brittle. We could get a PDF, but not a predictable one that matched our brand every time. The ecosystem fragmentation also showed. Dialects multiplied, extensions conflicted, and onboarding turned into learning a tool stack rather than writing.

AsciiDoc solved these recurring issues. We gained first class cross references, attributes, includes, and conditions. We kept documents modular so diffs became meaningful rather than walls of rewrapped text. HTML and PDF builds became deterministic once we standardized the toolchain, and designers could set a single theme to govern both outputs. At some point we even decided to take the experience to another level on Apple devices and create our own AsciiDoc text editor that relies on a single stylesheet for all output formats and needs no terminal for exporting. But that is a story for another time. The point is, we truly fell in love with the power and simplicity behind AsciiDoc.

We wanted structured writing that non experts can join, predictable builds for both web and PDF, and reviews that concentrate on content. AsciiDoc gave us exactly that and much more.