I Built docproof: a CLI That Tests Your Documentation by Running It

This is a really practical idea. Documentation can easily become outdated when commands or APIs change, so actually running the code examples is a much better check than reviewing the README manually. The CI integration also makes it especially useful for keeping documentation reliable over time.

"Documentation is code that hasn't been executed" is the reframe that makes this whole tool obvious in hindsight, every other artifact in a repo gets a CI check the moment it can be automated, and the README was exempt purely because nobody built the runner, not because it mattered less.

The skip-directive design is the part I'd point to as the actual engineering insight, not the extraction/execution pipeline. A doc-testing tool that fails on every install command or credentialed API call would get disabled within a week, so the real work was building an escape hatch precise enough that "illustrative by design" and "actually broken" stay distinguishable, and the AI prompt explicitly being told "suggest a skip directive" instead of forcibly rewriting unrunnable samples is the same insight applied one layer up.

Sequential-shared-workspace-per-file over parallel execution is a good example of resisting the more impressive-sounding default. Parallel would demo well and be structurally wrong the moment a doc has a "create config, then read config" pattern, which is most real tutorials, matching execution order to how people actually write docs mattered more than raw throughput here.

LLove this perspective - it really makes me think about my priorities.

Nice article!