15 tests passed on two operating systems. Then I pointed the checker at my own docs and it lit up false. A bash pipefail trap, and why an orphan doc is dead code.
Documentation checker passed 15 tests but broke on real files: a pipe+grep -q edge case hidden until scale. Synthetic test fixtures don't surface production bugs—dogfooding your own tool against real data is the actual quality test.
A broken doc still renders.
That is the whole reason documentation rot is so dangerous.
The page looks fine right up to the moment someone clicks the link that went nowhere.
This week I shipped a small tool to catch that, and the tool taught me a lesson I keep relearning.
What the tool does
My CI was green. 1,885 tests, 66 packages, zero failures. go vet clean. The build was a single...
When CI goes red on a diff that doesn't touch the failing surface, the working hypothesis isn't 'what did I break?' It's 'what…
You know the moment. You open a doc, you trust it, you build on it — and it turns out that doc has...
The Technical Problem: Websites Drift, Pipelines Don't Know Long-running scraping...
There is one thing worse than a codebase with no documentation: a codebase with documentation that...
if you've ever shipped an SDK update and then, three weeks later, a GitHub issue lands saying "the...
