Make every page easy to operate
Good documentation is a product surface for both people and agents. Keep concepts explicit, examples executable, and every next action visible.
Structure for retrieval
Give each page one job, use descriptive headings, and put the operation name beside the explanation. An agent should be able to identify the required headers and the next page without reading the whole site.
Prefer examples
Examples should use real Cartly field names, include the request context, and show the smallest useful response. Keep longer schemas in the API reference rather than duplicating them in guides.
State guardrails
Tokens stay server-side. Checkout retries reuse an idempotency key. Prices and totals always come from Cartly.