Posts about documentation workflows and tooling.
View All TagsBefore I started this portfolio-with-a-pipeline project, I didn't know that pinning a version was something anyone needed to do. Now, I know it's one of the things keeping my pipeline from breaking when a software version updates.
I was talking with a technical writer recently who doesn't use GitHub. They'd been reading about docs-as-code pipelines and wanted to know whether they were technical enough to build one with Claude Code or a similar AI assistant.
It's a fair question, and I didn't want to just answer it with a pep talk. This is what happened on my own pipeline this week, including the part I'm less proud of.
There is a file in this repo called pipeline.md. It exists so an AI agent can read a straight description of how this site's documentation pipeline works. It's the file my whole "documentation for machines" argument rests on.
Until last week, it had no front matter. None. It opened on an H1. That's one of the dangers when you build something with an AI coding assistant like Claude Code, I guess.
Vale read it. Doc Detective read it. Docusaurus built it. Every check passed, including me physically looking at it.
The monthly reviewer I built to catch stale content caught something on its first real run. It wasn't a stale file; it was an assumption I (through Claude) had been carrying for weeks, unverified, since I fixed a dead link and moved on.
For seven weeks, my site's llms.txt told an AI agent my pipeline ran three custom Vale rules. It ran five. The test I'd built specifically to catch that kind of thing kept passing the whole time.
I had a Doc Detective test planned for months: point checkLink at the work samples on my portfolio page, same as I do for every other link on this site with Lychee. Then I sat down to actually build it, and realized the plan didn't hold up.
I've had three custom Claude Code skills and a CLAUDE.md file running in this pipeline for weeks. Both live in the repo itself, not on my local machine. For the specifics of how they work, see Skills and CLAUDE.md. This post is about something those pages don't cover: why I reach for one over the other, and what each one is actually buying me.
My AI coding assistant spent days confidently describing a test that wasn't actually running. Here's how I caught it — and what that says about who still needs to be doing the noticing.
I set out to write a test that takes two screenshots of the homepage: one small picture, one big picture. The idea was simple enough that I expected to spend most of my time on the page copy, not the test. Instead, I hit a crash in Doc Detective itself, and then a browser that quietly refused to be as narrow as I asked it to be.
Really, now. I do not expect that kind of recalcitrance from my apps.
As part of my continuing journey into documentation testing, I set out to write a test that takes a screenshot of a live API reference. It sounded simple: load the page, wait for it to render, take a picture. Then I asked Claude Code what the test was actually checking, and had to admit the honest answer was "not much."