Technical writing blog
Technical writing for people who build documentation systems
Practical approaches to docs-as-code, structured authoring, DITA, automation, and AI-assisted documentation.
Recently published
Latest articles
-
Graph theory for information architecture
A sitemap tells readers where pages live. A graph tells you how they relate: which pages are orphans, which ones hold the network together, and whether a reader can actually get from a question to a finished task.
-
A frozen layout doesn’t freeze the content: working under a design veto
The decision-makers kept the legacy layout, against my recommendation. But a veto on the form layer doesn’t reach the others. Separation of concerns let me improve the boilerplate prose and the way structured data: phone numbers: is presented, without touching the page the deciders wanted left alone.
-
From tables to layers: progressive disclosure in a documentation table
A table puts every column in front of every reader at once. Progressive disclosure shows the essential column first and keeps the rest a single selection away, which is David Farkas’s idea of layering as a safety net for minimalist documentation.
-
The manual is the API
A coding agent, a support chatbot, and a RAG pipeline all need a reliable way to find and fetch relevant content from a documentation site, without scraping HTML or guessing URLs. How one documentation manual turns its existing corpus into that interface, without building a second system for it.
-
CI/CD for a print artifact: one principle, two projects
Running make locally is one thing. Guaranteeing that every contributor’s push or YAML edit on GitHub produces the same press-ready artifact on a clean machine with a pinned toolchain is another. How two print projects implement that guarantee with GitHub Actions.
-
You Probably Don’t Need a CMS: Building a Lightweight Admin with Git and Astro
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.
02 / Taxonomy graph
Explore by topic
Each circle is a topic, sized by its number of articles; a line joins topics that often appear together.
Circle size shows how many articles use a topic. A line joins two topics that appear together in at least 2 articles, thicker when they share more. Each topic links to its articles.
03 / Systems architecture · Case study
Documentation systems
Notes on decisions I have made while building and maintaining documentation systems.
One YAML source file feeds three paths: an OpenAPI schema rendered as interactive Swagger UI, an Astro build that prerenders HTML tables and lists, and a REST API route that returns JSON to fetch, curl, and client applications.
AI documentation assistant
Explore the articles
Ask a question in plain language. The assistant answers from the articles published on this site, grounded in their text, and lists the ones it used. To look up an exact term, use search.
Answer
Sources
Try rephrasing with a more specific term, browse by topic, or search the articles.
Need methods, templates, and case studies? See the technical writing practice (opens in a new tab).
05 / Colophon
About the blog
A technical writing blog by Olivier Carrère: docs-as-code, structured authoring and DITA, Markdown and YAML, documentation architecture and automation, and AI-assisted documentation.
docs.redaction-technique.org
Technical writing practice
A bilingual collection of technical-writing methods, case studies, worked examples, and documentation projects. Built and maintained in Git since 2014.
Explore the practice (opens in a new tab)