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
The soft hyphen (U+00AD): the invisible character that breaks PDF text extraction
It's invisible on screen. It prints correctly. But when text is extracted from the PDF - by an accessibility checker, a search engine, or a copy-paste - U+00AD surfaces as a garbage character between syllables. Here's what it is, where it comes from, and how to find it.
One source, three languages: the strict facts-vs-display-strings split
events.yaml holds no labels. traduction.yaml holds no facts. The generator resolves them at build time with --lang fr, --lang en, or --lang es. What enforcing this constraint looks like in practice, and why the discipline is worth the friction it creates.
Reliability vs. latency: running Claude through the CLI so it can fix its own mistakes
Claude's LaTeX output frequently didn't compile. The fix wasn't to prompt better - it was to close the feedback loop. What looked like a reliability problem turned out to be a latency problem.
More articles
-
Persona prompting: you’re an experienced typographer, check this before printing · 6 min -
PDF/X-4 from LuaLaTeX without Ghostscript: TrimBox, BleedBox, FOGRA39, and the pdfx package · 7 min -
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