When linting isn’t enough: structure, AI, and documentation
Explore how AI and deterministic structural checks could help a docs-as-code pipeline validate whether Markdown content fits its intended purpose.
Topic
Docs-as-Code
-
-
Graph theory for information architecture
A sitemap tells readers where pages live. A graph tells you how they relate: which pages are orphans, which ones hold the network together, and whether a reader can actually get from a question to a finished task.
-
A frozen layout doesn’t freeze the content: working under a design veto
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.
-
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.
-
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.
-
Three levels of technical documentation: wasteland, English garden, French garden
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.
-
RGB to CMYK in Python: Pillow, LittleCMS, and the principle of checking without faking
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.
-
The soft hyphen (U+00AD): the invisible character that breaks PDF text extraction
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.
-
One source, three languages: the strict facts-vs-display-strings split
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.
-
PDF/X-4 from LuaLaTeX without Ghostscript: TrimBox, BleedBox, FOGRA39, and the pdfx package
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.
-
Non-blocking preflight, or: a build that always produces a PDF
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.
-
Why hand-maintained InDesign files rot — and what docs-as-code does instead
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.
-
Manage content in files, not databases
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.
-
Strong information typing without the XML overhead
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.
-
A web journey: from HTML to Git-based Markdown workflows
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.
