February 10, 2026
Docs vs Types: FIGHT!
Ship Types, Not Docs
Throw out the manuals, ship the blueprint—cheers and side‑eye
TLDR: A viral post says to skip manuals and ship code-checked types so humans and AI can integrate without guesswork. Commenters split: types may nail the “how,” but people still need plain-language “why,” while others ask if AI can autowrite docs—or whether this is just GraphQL by another name.
Developers are passing around a spicy manifesto: throw out stale manuals and ship types—machine-checked blueprints that live in the code—so integrations stop crashing at 2am. The post mocks the classic saga: copy the example, get a 400 error, discover a secret header, wait half a day to learn the docs are for a different version. The claim: docs drift, code doesn’t; types are the truth, and with AI assistants becoming heavy users, the codebase itself needs a friendly user experience. If the blueprint compiles, it works. No late-night Slack hunts, no mystery fields, no broken promises. Cloudflare’s own JavaScript remote calls get the hero edit as proof that contracts can be enforced before anything hits production.
But the comments are where the fireworks pop. One top reply argues code only explains the how, not the why: you still need human words to tell people what to do with the results—“the only ‘docs’ you need are ‘how do I call this’,” they quote, then push back. Another voice lobs a curveball: can LLMs (big text-predicting AIs) automatically keep docs up to date? And a drive-by quip lands: “so like GraphQL?” Cue memes about “400 Bad Request bingo” and groans about “documentation drift,” while pragmatists warn that no blueprint replaces a good map. Verdict: the crowd loves the speed, but no one’s burying human guidance just yet.
Key Points
- •The article argues that API contract documentation often drifts from code, causing integration errors due to version and field mismatches.
- •It advocates shipping types (schemas) as the contract instead of prose, making the code the single source of truth.
- •Types enable developers and AI agents to generate correct code and validate requests at compile/transpilation time.
- •Prose documentation should remain for explaining purpose, usage context, and architecture, but not for the contract itself.
- •Cloudflare’s Developer Platform uses JavaScript-native RPC to enforce contracts at transpilation time, contrasting with error-prone traditional HTTP API integrations.