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
-
Information Architecture
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.
-
Docs-as-Code
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.
-
Minimalism
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.
-
API
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.
Index
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.
Featured article
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).
About
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)