Reference pages should remain precise and scannable, but developers also need a conceptual map. Explain the core objects, authentication model, lifecycle, limits, and the shortest path to a successful first request.
What matters in practice
Examples should be runnable and realistic. Include common errors, retry behavior, pagination, idempotency, and security considerations beside the feature they affect rather than hiding them in separate documents.
A useful rule
Treat documentation like product code: version it, test examples, observe search queries, and give users a clear way to report gaps. Useful documentation reduces support load and increases trust.