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, Markdown, and YAML.
Most of a small organization's website barely changes. This is an argument for building the smallest editing interface it actually needs, using Astro, Git, YAML, and a small admin layer instead of a full CMS.
A GUI hides complex code behind menus and drag handles you operate by hand. AI hides the same complexity behind a conversation. Recreating a hand-built InDesign leaflet as a YAML-to-LaTeX pipeline: abandoned in 2025 as beyond the time I could afford: is what made the difference concrete.
DITA XML can shrink the volume a technical writer creates, translates, and maintains: and a firewall vendor once got its documentation praised by the press because of it. But the productivity comes with a complexity bill. Here’s where structured authoring earns its keep, and where it’s overkill.
Chronological archive of technical documentation essays
