Technical writing for people who build documentation systems

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

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

  Sep 17, 2026·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.

  Sep 15, 2026·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.

  Sep 8, 2026·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.

  Sep 1, 2026·3 min read

  →

• DITA XML

  Structured authoring’s hidden bill: when DITA XML pays off, and when it doesn’t

  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.

  Aug 25, 2026·3 min read

  →

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

• Documentation

  • Developer documentation
  • API documentation
  • Technical documentation
  • Information architecture

  Developer guides and API reference reviewed with engineers, from reference templates to OpenAPI generated from a single source, organized by concept, task, and reference.

  Expertise: Developer & API documentation (opens in a new tab) · Documentation process & quality (opens in a new tab) · Multilingual documentation (opens in a new tab)

• Methods & standards

  • Docs-as-code
  • Structured authoring
  • DITA
  • Documentation architecture

  Documentation in Git next to the product, topic-based DITA XML with content reuse and conditional text, and an architecture that keeps large documentation sets consistent.

  Expertise: Docs-as-code (opens in a new tab) · DITA & structured authoring (opens in a new tab) · Documentation architecture (opens in a new tab)

• Engineering workflow

  • Git and pull-request review
  • CI/CD
  • Automation
  • Markdown, YAML, XML

  Reproducible builds with pinned toolchains, automated checks, publishing pipelines, and content generated from data. I use AI for selected documentation tasks, with human review before publication.

  Expertise: Automation & CI/CD (opens in a new tab) · AI-assisted documentation (opens in a new tab)

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