Markup and Meaning
Practical writing on docs-as-code, structured authoring, and AI-assisted documentation - how the right structure and tooling make docs scale without losing clarity. By Olivier Carrère, a technical writer working in DITA XML and Markdown.
Latest
When to take the helm back: retiring a docs pipeline once the work turns editorial
A generated LaTeX book taught me the rarer docs-as-code move - not building a pipeline, but dissolving one. When every remaining edit is a one-off typographic judgment, a 453-line generator stops earning its keep, and the right call is to freeze its output, delete the generator, and edit the source by hand.
Persona prompting: you’re an experienced typographer, check this before printing
The same PDF, two different prompts. 'Is this well laid out?' returned vague positivity. 'You're an experienced typographer, check this before printing' returned a structured technical review. The before/after register change is a clean, demonstrable lesson.
PDF/X-4 from LuaLaTeX without Ghostscript: TrimBox, BleedBox, FOGRA39, and the pdfx package
Producing a PDF/X-4 press-ready file from LuaLaTeX without touching Ghostscript: the pdfx package, TrimBox/BleedBox geometry in points, FOGRA39 OutputIntent, CMYK-only color discipline, and XMP metadata - everything a print shop will verify.
More articles
-
Non-blocking preflight, or: a build that always produces a PDF · 9 min -
Why hand-maintained InDesign files rot - and what docs-as-code does instead · 13 min -
Transforming a corpus of 7,000 pages into living knowledge · 8 min -
1.8 million words, freed from Word 97 and made searchable · 8 min -
Less is more: from psychology to technical writing · 6 min -
Slow food for fast thinking: designing with cognitive ease in mind · 8 min -
What YAML gives technical docs that XML and Markdown can't · 10 min -
One YAML file, three outputs: API docs, web, and mobile · 3 min -
Translating legacy French docs to English with DeepL and GPT-4o · 4 min -
Manage content in files, not databases · 6 min -
Strong information typing without the XML overhead · 4 min -
A decade of Word 97 conference files, rebuilt for the web for $30 · 5 min -
From DITA XML to Markdown: lightweight information typing · 2 min -
A web journey: from HTML to Git-based Markdown workflows · 4 min