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
-
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.
-
Docs-as-Code
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.
-
Astro
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.
-
AI
AI will soon replace GUIs: rebuilding an InDesign leaflet through conversation, not clicks
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.
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)