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.
Articles
Latest articles
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.
-
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.
-
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.
Index
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.
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 the author
Expertise
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)
Problems I have worked on
Selected work
-
Single-source API documentation
- Reference data copied into docs, web pages, and app views drifts out of sync.
- One YAML file in Git generates OpenAPI/Swagger documentation, prerendered HTML tables, and JSON for apps.
- Using one machine-readable source for API reference, web content, and application data.
See the work: Single-source API documentation Live API docs: Single-source API documentation
-
NuFirewall product documentation
- Keep software product documentation consistent across deliverables and languages without duplicating sources.
- Wrote it in DITA XML: centralized conrefs, ditaval conditional text, and translation-ready topics.
- Structured the product documentation for reuse; the result was later cited by the press.
View the case study: NuFirewall product documentation (opens in a new tab) When DITA pays off: NuFirewall product documentation
-
CI/CD for print deliverables
- Builds on contributors' machines drifted: toolchain updates moved layouts, and RGB images reached the press.
- GitHub Actions pipelines for two print projects: pinned TeX Live, CMYK conversion, and PDF/X-4 preflight checks.
- Turning a fragile local print workflow into reproducible, validated builds.
See the work: CI/CD for print deliverables Example CI/CD pipeline: CI/CD for print deliverables (opens in a new tab)
-
Technical writing practice
- Keep a bilingual collection of technical-writing methods, case studies, worked examples, and documentation projects accurate and maintainable over more than a decade.
- In Git since 2014: from WordPress to reStructuredText and DITA XML, now Astro with CI builds and a machine-readable API.
- Maintaining the documentation set across successive tools, architectures, and languages.
See how it is built: Technical writing practice (opens in a new tab) Translating it with AI: Technical writing practice
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.
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 new opportunities in technical writing, developer documentation, documentation architecture, and docs-as-code.
To discuss a technical writing role or project, reach me on LinkedIn or use the contact form.