Skip to content

Markup and meaning

Technical writing for people who build documentation systems

Practical approaches to docs-as-code, structured authoring, DITA, automation, and AI-assisted documentation.

By Olivier Carrère , Senior Technical Writer , Rédacteur technique senior

Available for a new opportunity from October 2026
Current contract ending October 1, 2026.

Open to permanent Senior Technical Writer opportunities with engineering and product teams: developer and API documentation, docs-as-code, structured authoring (DITA XML), and automated CI/CD publishing pipelines.

How I contribute Selected work Technical writing practice (opens in a new tab)

Recently published

Latest articles

View all 26 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.

    10 min read

  • 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.

    12 min read

  • 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.

    18 min read

  • 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.

    3 min read

About the author

Expertise

Explore my expertise (opens in a new tab)

I work with engineering teams on developer and API documentation, from information architecture and authoring to automated builds, checks, and publishing.

Articles

Documentation systems

Notes on decisions I have made while building and maintaining documentation systems.

YAML Multi-Output API Architecture Diagram

YAML Source File
oil-types.yaml

OpenAPI Schema
/api/oil-types/schema

Astro Build Engine
Static prerendering

REST API Route
/api/oil-types

Interactive Swagger UI
/docs

Prerendered HTML
SEO tables & lists

JSON Response
fetch / curl

Client Applications
Mobile & web apps

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.

Multi-output publishing architecture: single YAML dataset driving responsive web pages and machine-readable API endpoints.
Single-source API documentation

Explore by topic

Explore how the topics in my work connect.

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.

Explore all topics

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.

Answers are generated from this site’s articles only.

Docs-as-code

Engineering workflow

Documentation in Git next to the product: branches, pull-request review, repository design, and automated publishing.

  1. Content

    Markdown, YAML, XML, and topic-based DITA XML with content reuse.

  2. Git

    Branches, pull-request review, and repository design.

  3. Validation

    Schema checks, link verification, and preflight tests in pull requests.

  4. Build

    Reproducible builds with pinned toolchains.

  5. Publication

    Automated CI/CD publishing pipelines.

AI-assisted documentation

One part of the documentation workflow, always with human review: first-draft and translation assistance, content transformation, quality checks, and a documentation API for AI agents.

Expertise: AI-assisted documentation (opens in a new tab)

Problems I have worked on

Selected work

Evidence of technical writing, structured authoring, and documentation engineering contributions.

  1. Developer documentation · Single-sourcing

    Single-source API documentation

    Problem
    Reference data copied manually into API documentation, web pages, and application views drifts out of sync.
    Contribution
    Architected a single YAML source of truth in Git and authored the build pipeline generating interactive OpenAPI/Swagger docs, static HTML tables, and REST JSON payloads from one dataset.
    Demonstrates
    Demonstrates single-sourcing from a machine-readable data model to reduce content drift across API references, static web documentation, and client application payloads.

    See the work: Single-source API documentation Live API docs: Single-source API documentation

  2. Structured authoring · Content reuse · DITA XML Role: Technical Writer

    NuFirewall product documentation

    Problem
    Keep enterprise firewall software documentation consistent across multiple deliverables and languages without duplicating sources.
    Contribution
    Structured the product documentation suite in DITA XML using centralized conref libraries, ditaval conditional text for target user profiles, and translation-ready modular topics.
    Demonstrates
    Demonstrates structured authoring in DITA XML with centralized conref reuse and ditaval profiling across deliverables and languages, using reusable content structures to support translation workflows and earning press recognition for documentation quality.

    View the case study: NuFirewall product documentation (opens in a new tab) When DITA pays off: NuFirewall product documentation

  3. Documentation engineering · Automated validation & CI/CD

    CI/CD for print deliverables

    Problem
    Document builds on contributors' machines drifted: toolchain updates altered layouts, and unverified RGB images reached the press.
    Contribution
    Built GitHub Actions CI/CD pipelines with pinned toolchains, automated CMYK color conversion, and non-blocking PDF/X-4 preflight validation for multi-author publications.
    Demonstrates
    Demonstrates docs-as-code automation for publications, using GitHub Actions, pinned toolchains, automated CMYK conversion, and preflight validation to check PDF/X-4 compliance in CI.

    See the work: CI/CD for print deliverables Example CI/CD pipeline: CI/CD for print deliverables (opens in a new tab)

  4. Documentation architecture · Content lifecycle & maintenance

    Technical writing practice

    Problem
    Keep a bilingual collection of technical-writing methods, case studies, worked examples, and documentation projects accurate and maintainable over more than a decade.
    Contribution
    Architected and maintained the documentation set in Git since 2014, evolving it across formats (WordPress to reST/DITA, now Astro) with automated CI validation, bilingual parity, and an agent-ready documentation API.
    Demonstrates
    Demonstrates long-term documentation lifecycle management and architectural evolution, maintaining a bilingual technical knowledge base across platform migrations and continuous automated delivery.

    See how it is built: Technical writing practice (opens in a new tab) Translating it with AI: Technical writing practice

Team integration

How I contribute to a team

How I work as an embedded technical writer within product, engineering, and documentation organizations.

  • Developer & API documentation

    Technical writing

    Authoring developer guides, API references, architecture overviews, and code-adjacent documentation directly with engineers and subject-matter experts. Structured by concept, task, and reference to explain complex systems accurately.

  • Information architecture & structured content

    Documentation systems

    Designing scalable content models, docs-as-code repository structures, and topic-based DITA XML libraries. Establishing shared templates and content reuse so multiple contributors write consistently without duplication.

  • CI/CD, automation & validation

    Documentation engineering

    Building Git workflows, CI/CD automation, and reproducible builds with pinned toolchains. Enforcing quality with automated validation gates: schema checks, link verification, and preflight tests in pull requests.

  • Engineering alignment & release integration

    Team collaboration

    Embedding documentation into sprint cycles and release workflows. Collaborating with engineers, product managers, and translators to ensure documentation is reviewed, validated, and published in lockstep with software releases.

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)

Contact

Get in touch

Available for a new opportunity from October 2026

My current Senior Technical Writer contract at Unity ends on October 1, 2026. I am open to a permanent Senior Technical Writer role in developer documentation, documentation architecture, and docs-as-code.

Reach me on LinkedIn or through the contact form to discuss permanent Senior Technical Writer opportunities or documentation systems.

LinkedIn (opens in a new tab) Contact form About Olivier