Working docs-first
Most of the bugs in this rebuild were not typos. They were configs that looked right because they matched an older version’s documentation: a Traefik option moved from middlewares to services, a Docker image renamed its log levels, a Gitea runner project was renamed and re-versioned. The fix in every case was the same: read the docs for the version you actually run.
Three sources, in order of authority
Section titled “Three sources, in order of authority”- The installed software itself.
--help, generated man pages, the package’s own type definitions. For restic,restic backup --helpsettled which environment variable it reads. For the Resend SDK, its.d.tsfile showed the option names. - The docs shipped with the installed version. Next.js 16 ships its full
docs in
node_modules/next/dist/docs/— version-exact. - A searchable mirror of upstream docs. Complete, but it can be ahead of what you run (a canary branch), so confirm against 1 or 2.
The local docs mirror
Section titled “The local docs mirror”This rebuild used a local, git-synced mirror of upstream documentation with
keyword and semantic search (docs <package> "<query>"). Two habits made it
reliable:
- Keyword search for exact identifiers, semantic for questions. Semantic search missed “using the current date in a Server Component”; a keyword search for the error name found the page immediately.
- A miss is a finding, not an answer. When a page wasn’t found, the next step was a broader keyword search, then the installed package, then the web.
When a dependency had no local docs (Resend, Cloudflare Turnstile), the docs were added to the mirror before writing the code that depends on them — and the code cites the page it came from.
Cite as you go
Section titled “Cite as you go”Every non-obvious line of config in the finished repos carries a comment naming the doc page it came from. When something changes upstream, that comment is where you start.