A platform's documentation is comprehensive and developers still get things wrong. What kind of documentation is missing?

What is missing

Documentation of guarantees and behaviour, rather than of interfaces.

Reference documentation describes syntax — endpoints, parameters, response shapes. What breaks integrations is semantics: what the system promises, what it does not, and how it behaves under conditions the happy path does not cover.

The specific gaps

1. Consistency and freshness guarantees. Is a write immediately visible to a subsequent read? Does search reflect a change instantly or with lag? Developers assume read-after-write and build workflows that fail intermittently exactly where the system is eventually consistent — and nothing told them otherwise.

2. Failure behaviour. Which errors are retryable, which are permanent, which indicate a client bug. A developer facing an error needs to know whether retrying is correct or harmful.

3. Limits and their mechanics. Not just the numbers but how they work: per what, over what window, with what burst behaviour, and what a rejection tells the client to do.

4. Idempotency semantics — which operations are safe to retry, how keys are scoped, how long they are retained.

5. What the system does not guarantee. "Search is eventually consistent; expect up to N seconds of lag" prevents an entire class of bug and costs one sentence. Every guarantee left unstated is one a developer will assume, usually the strongest one.

What else helps disproportionately

Working examples for the hard cases, not the easy ones: paginating a large collection safely, handling a rate limit, retrying idempotently, resuming an interrupted transfer. The trivial example is not where developers struggle.

A changelog that includes behavioural changes, not just schema changes. A latency characteristic or a consistency window that shifts silently breaks integrations that were correct.

A sandbox that behaves realistically — with limits, eventual consistency and occasional failures. A sandbox faster and more consistent than production teaches developers to build integrations that only work there.

The organising principle

Document the contract, not the interface. The interface tells a developer how to make one call succeed. The contract tells them how to build something that keeps working — and for a platform whose users are developers, the contract is the product.