Archive
28 notes on technical communication, docs-as-code, structured authoring, and AI-assisted workflows, newest first. Browse them by topic or search them.
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.
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.
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.
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.
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.
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 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.
Technical documentation is like a garden, and it grows in three stages. The wasteland has no process and no owner. The English garden is cultivated but informal. The French garden is structured and deliberate. Knowing which one you’re standing in tells you what to fix next: and what not to.
The prepare_images.py walkthrough: converting every source image to CMYK using the FOGRA39 ICC profile via Pillow and LittleCMS, with black-point compensation. Resolution is checked at placed size: never faked, never upscaled.
It’s invisible on screen. It prints correctly. But when text is extracted from the PDF — by an accessibility checker, a search engine, or a copy-paste — U+00AD surfaces as a garbage character between syllables. Here’s what it is, where it comes from, and how to find it.
events.yaml holds no labels. traduction.yaml holds no facts. The generator resolves them at build time with --lang fr, --lang en, or --lang es. What enforcing this constraint looks like in practice, and why the discipline is worth the friction it creates.
Claude’s LaTeX output frequently didn’t compile. The fix wasn’t to prompt better — it was to close the feedback loop. What looked like a reliability problem turned out to be a latency problem.
The same PDF, two different prompts. 'Is this well laid out?' returned vague positivity. 'You’re an experienced typographer, check this before printing’ returned a structured technical review. The before/after register change is a clean, demonstrable lesson.
Producing a PDF/X-4 press-ready file from LuaLaTeX without touching Ghostscript: the pdfx package, TrimBox/BleedBox geometry in points, FOGRA39 OutputIntent, CMYK-only color discipline, and XMP metadata — everything a print shop will verify.
One hard stop, five soft failures, a renamed file, and a report alongside it. The design philosophy behind a preflight that never aborts — plus the pikepdf/PyMuPDF six-check implementation and the --strict flag for CI.
A 370-cell calendar that shifts every year. A lead’s name in three places. An IBAN in an invisible text box. These are not unusual InDesign problems — they are what InDesign files become when they accumulate facts with no single home. Two projects show what the alternative looks like — and where InDesign’s own global tools stop short.
From a massive archive of 7,000 pages to daily insights, quote retrieval, and AI-powered thematic digests: this project turns static content into a living flow of clarity, focus, and well-being.
1,800 lecture transcripts — 1.8 million words once trapped in Word 97 files — converted to Markdown, scored and tagged by AI, and turned into a searchable discovery platform that also generates print-ready LaTeX anthologies.
How Kahneman’s idea of 'less is more’ connects with minimalist documentation — and how layering keeps clarity from becoming oversimplification.
What can Kahneman’s Systems 1 and 2 teach us about technical writing? This post explores how minimalism and DITA structure align with cognitive systems to make documentation more intuitive and human-centered.
A growing engine-oil catalog — brands, viscosities, prices — becomes a maintenance nightmare as a Markdown table and a verbose tangle as DITA XML. One YAML file holds each fact once and generates every table, doc page, and app view from it.
Learn how one YAML file can serve as a single source of truth for APIs, powering docs, HTML documentation, and even mobile apps.
Professionally translating hundreds of legacy French Markdown files would have cost a fortune. Instead, a DeepL-then-GPT-4o pipeline with Git diffs as a safety net: keep the good translations file by file, discard the rest, rebuild.
Databases are not always the best place for your content. By storing it in plain files, you gain speed, security, Git-based workflows, and a simpler, more reliable publishing stack.
You don’t need the complexity of DITA XML to benefit from its discipline. With Markdown and modern docs-as-code workflows, technical writers can apply strong information typing-tasks, concepts, and references-using lightweight, open tools.
How we transformed unstructured Word 97/2000 files into a decade-long web publication of conferences-using Markdown, Python, and GPT-powered automation for just $30.
DITA brought structure through XML, but its complexity often felt heavy. Markdown offers a lightweight alternative where technical writers can still apply DITA’s information typing principles — using open, freely available tools and without the XML overhead.
Tracing over two decades of web publishing, from raw HTML and Dreamweaver to CMSes, structured content, static site generators, and modern Git-based Markdown workflows. Lessons for solo and team content developers on maintainability, collaboration, and performance.
