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
Three levels of technical documentation: wasteland, English garden, French garden
Technical documentation is like a garden, and it grows in three stages. The wasteland has no process and no owner. The English garden is cultivated but informal. The French garden is structured and deliberate. Knowing which one you're standing in tells you what to fix next: and what not to.
RGB to CMYK in Python: Pillow, LittleCMS, and the principle of checking without faking
The prepare_images.py walkthrough: converting every source image to CMYK using the FOGRA39 ICC profile via Pillow and LittleCMS, with black-point compensation. Resolution is checked at placed size: never faked, never upscaled.
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.
More articles
-
One source, three languages: the strict facts-vs-display-strings split · 7 min -
Reliability vs. latency: running Claude through the CLI so it can fix its own mistakes · 7 min -
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