How a hand-written guide proves it’s still true

The problem with curated anything

The exhaustive docs can’t lie: a tool reads the library from the compiler and writes down what’s there. The guide is different. Its value — “use this, not that” — is judgment a person typed in by hand, and anything typed by hand can drift out of date. A library update renames a function; the guide keeps pointing at the old name; and now it confidently sends you somewhere that no longer exists.

A confident wrong answer is worse than no answer. So the real question isn’t “is the guide correct today?” — it’s “how do we know it’s still correct, every time, without re-reading it by hand?”

One source, nothing invented

First, there is exactly one copy of the guide — a single file that everything else is generated from. There is no second list to fall out of sync, and every entry traces back to a checked source rather than to someone’s memory. The rule while writing it was strict: if you can’t point at where a symbol’s name came from, you don’t get to write it down. No plausible-sounding guesses. This isn’t paranoia. Earlier in the project, an automated draft of a related list cited two functions that sounded real and weren’t — caught only by checking against the actual library. Plausible and true are different things.

The build refuses to ship a dead reference

Here is the part that does the real work. Every time the documentation is built, the guide is held up against the live library — the same one read straight from the compiler — and every Closure symbol it names is checked to be really there. If even one has gone missing, the build doesn’t paper over it or warn quietly. It stops, and names the symbol that’s gone.

Say a future library version renames goog.functions.debounce. The guide still says “debounce → goog.functions.debounce.” The next build looks for that symbol, can’t find it, and halts with that exact name. Nobody ships a broken pointer, because the broken pointer makes the build fail. The curation stays human; the checking of it is mechanical and relentless.

The guarantee that grows by itself

There is a second, quieter check underneath. Every link the guide renders — from a need to a symbol’s page — is verified to land on a page that actually exists, at the right spot on it. And because that check walks whatever links are present, it covers new entries for free.

We saw this directly. The guide started as a 5-row proof of concept and grew to its full 32 rows. That growth took the index to 55 links, and 94 new link-checks appeared on their own — nobody wrote them — and all of them passed. Each link is checked twice — the target page exists, and it carries the exact spot the link points to — so the 47 newly added links accounted for 94 checks. The test surface grew with the content, not with the test code. Add a row, and the safety net for that row knits itself.

Worth stealing

If you ever build a curated guide of your own — a cheat-sheet, a recommended-libraries list, an internal “use this, not that” — the shape here is the lesson, and it is small:

Keep one source of truth, not copies. Check it against reality at build time, not against your good intentions. And lean on checks that walk the content itself, so the guarantee grows every time the guide does. Curation can be as trustworthy as generated data — it just has to be made to prove itself, automatically, on every build.