API Documentation Vocabulary

Reference documentation is the "dictionary" of your API — comprehensive, precise, and structured for lookup rather than learning. It is the most commonly visited documentation type by experienced developers integrating your API.

The Diátaxis framework (by Daniele Procida) distinguishes four documentation types: Reference (information-oriented, comprehensive, dry), Tutorial (learning-oriented, step-by-step, narrative), How-to Guide (problem-oriented, task-focused), and Explanation (understanding-oriented, conceptual). Reference docs are the most technically demanding to maintain because they must match the implementation exactly — a single incorrect field name or missing parameter makes the reference unreliable. Best practice: auto-generate reference docs from the API definition (OpenAPI/Swagger for REST, protobuf for gRPC, GraphQL schema for GraphQL) so they stay in sync with code changes automatically.

Key vocabulary:
• reference documentation — comprehensive, structured information about every API element; designed for lookup by experienced users
• OpenAPI (Swagger) — a specification format for documenting REST APIs that enables auto-generated reference docs
• Diátaxis — a documentation framework distinguishing Reference, Tutorial, How-to, and Explanation as four distinct documentation needs

A great quickstart trades comprehensiveness for speed — its job is to create a "first win" that motivates the developer to invest time in learning the full API, not to document every feature.

The "10-minute quickstart" is a specific design goal used by companies like Stripe, Twilio, and GitHub: if a developer can make their first successful API call in 10 minutes, they are far more likely to continue integrating. Techniques for achieving this: (1) Use copy-pasteable code samples in the developer's language of choice (language selector); (2) Inline configuration — provide a pre-authenticated example so the developer doesn't need to read the auth docs first; (3) Immediate visual feedback — show the API response in the code sample so the developer knows what success looks like; (4) Minimal prerequisites — if you need to create an account, link to it rather than explaining the signup flow inline. The quickstart is the highest-traffic page in most API docs — it deserves the most writing and testing investment.

Key vocabulary:
• quickstart guide — a minimal, fast path to a first successful result; trades comprehensiveness for developer time-to-value
• happy path — the most common, successful use case without edge cases or error handling
• time to first successful call — a UX metric for API documentation measuring how quickly a new developer achieves their first working result

Concept guides are the most underrated documentation type — developers who understand the underlying model make better decisions, write better code, and require less support than those who only learned from examples.

A concept guide on the data model might explain: "This API uses a resource hierarchy: Organisations contain Projects, Projects contain Deployments. All permissions are scoped to the Project level. If you're used to flat resource models, the hierarchical scoping is the most important thing to understand before integrating." This context prevents a class of errors that would occur if the developer assumed flat scoping. Concept guides are especially valuable for: auth and permissions models (most complex and highest-stakes), data models (entities, relationships, identifiers), async patterns (webhooks, polling, event streams), and rate limiting (quotas, burst limits, backoff strategies). The Diátaxis term for this document type is "Explanation" — its goal is understanding, not task completion.

Key vocabulary:
• concept guide / explanation — documentation that explains the underlying model, architecture, or design decisions to build user understanding
• data model — the entities, relationships, and constraints that define the structure of the API's data
• contextual understanding — the mental model a developer builds of how a system works, which guides their use of reference and tutorial docs

Tutorials are the most expensive documentation to write and maintain because they require complete, working, realistic code examples — but they are the most effective at building deep developer competence and confidence with an API.

The Diátaxis distinction between tutorial and how-to guide: a tutorial teaches through a carefully designed learning experience ("follow this to learn X"); a how-to guide solves a specific problem the developer already has ("how do I do X?"). Tutorials are appropriate for: first-time users learning the API's core workflows, complex multi-step scenarios that require understanding before executing, and onboarding to non-obvious patterns (webhooks, pagination, retry logic). A "complete working example" typically means: full authentication setup, all required API calls in the correct sequence, error handling code, and the expected output — everything a developer needs to copy and run the example successfully without filling in missing pieces.

Key vocabulary:
• tutorial — a learning-oriented documentation type; teaches through a structured narrative scenario; explanatory at each step
• complete working example — a code sample covering authentication, the full API interaction, and error handling — runnable without gaps
• how-to guide — a task-oriented documentation type; answers "how do I do X?" for developers who already understand the system

The API changelog is a trust mechanism — it demonstrates that the API team respects the developers who have built on top of their API and will tell them explicitly when something changes that could break their integration.

Best practices for API changelogs: (1) Distinguish breaking vs. non-breaking changes clearly — "Added optional field X" (non-breaking) vs. "Removed field Y" (breaking) vs. "Changed field Z from string to integer" (breaking); (2) Provide migration guides for breaking changes — not just "field Y removed" but "use field W instead, here is how to update your integration"; (3) Provide advance notice for breaking changes (deprecation notices before removal); (4) Date every entry precisely; (5) Link to the relevant documentation for changed behaviour. Semantic versioning (semver) is the standard for communicating break scope: MAJOR version increments always indicate breaking changes, MINOR indicates non-breaking additions, PATCH indicates bug fixes.

Key vocabulary:
• changelog — a chronological record of changes to an API, clearly distinguishing breaking from non-breaking changes
• breaking change — a change that requires existing integrations to be updated to continue working correctly
• deprecation notice — advance warning that a feature will be removed in a future version, giving developers time to migrate