A team generates its entire API reference from code annotations and deletes the hand-written guide. Six months later integrators are opening more support tickets, not fewer, and every one of them is technically answerable from the reference. What did generation buy, and what did it destroy?

What generation genuinely buys

The reference cannot be wrong about shape. Every endpoint, field, type, enum value and status code is present, and it stays present after a refactor. That is not a small thing: the characteristic failure of hand-written reference documentation is drift, and drift is worse than absence, because an integrator trusts it.

For a platform of Hugging Face's shape, with a wide surface and rapid change, generation is the only mechanism that keeps the surface described at all.

What it destroys

A generated reference answers "what exists". Integrators fail on "what to do". The gap is specific and enumerable:

• Sequence. Which call comes first, what you carry from its response into the next one, what you poll, for how long, and what a timeout means.
• Failure semantics. The annotation says 409 Conflict. The integrator needs to know what conflicts in this domain, whether to retry, and whether the operation may have partially applied. No type system expresses that, and it is the most consequential thing in the documentation.
• Idempotency and retry rules, which are a property of the protocol between two systems and not of any single response.
• Quotas and behaviour at the boundary — what happens at the limit, what the reset semantics are, whether bursts are allowed.
• A worked example with real values, which is what people actually copy and adapt, and which no annotation produces.

When the bill arrives

Not at launch. It arrives as support ticket volume from integrations that are already live, because the questions are about behaviour under failure, and failure happens after go-live. The team reads the tickets, confirms each one is answerable from the reference, and concludes the integrators did not read it — which is the wrong conclusion, because the reference does not contain the answer in a form anyone can find.

The design that keeps both

• Generated reference as the substrate. Do not hand-write anything derivable from code.
• A small number of task-oriented guides, hand-written: "take a payment", "handle a webhook you failed to process", "migrate to v3". Five to ten of these cover most integration work.
• Examples under test. Every snippet in the hand-written material runs in CI against the real API, so the part you write by hand cannot drift either. This is what makes the hybrid stable rather than a slow return to the original problem.

The decision rule: generate what the code knows, write what the code cannot express, and put the written part under test.

When not to bother

An internal API with two consumers needs a README and a conversation. Task guides, tested examples and a documentation pipeline for an interface that two teams in one building call is process applied where a message would do.