Skip to main content

​
Developer doc types (Diataxis + agent layer)

Every page on docs.zapier.com is one of four types. Choosing the right type first, then following its template, keeps pages predictable for human scanners and AI agents alike. This extends the writing rules in writing-standards-dev-docs. This structure follows the Diataxis framework — four page types organized by whether the reader is learning or working, and whether the content is practical or theoretical. Tutorials and how-tos are practical (doing); explanations and reference are theoretical (understanding). Tutorials and explanations serve learning; how-tos and reference serve working.

​
Choose the type

Is the reader learning a skill by doing?          → Tutorial    (Quickstart, walkthrough)
Is the reader accomplishing a known goal?         → How-to      (Task, Troubleshooting)
Is the reader trying to understand something?     → Explanation (Concept)
Is the reader looking up a specific fact?         → Reference   (Errors, limits, API reference)
TypePrimary questionTitle styleTemplate (owns the full schema)
Tutorial”How do I get something working?”Verb phrase (“Create your first…“)template-tutorial
How-to (task, troubleshooting)“How do I do or fix this specific thing?”Verb phrase (“Manage your inbox”)template-how-to
Explanation (concept)“What is this and why does it work this way?”Noun phrase (“What is …?“)template-concept
Reference (errors, limits, glossary)“What exactly does this mean or do?”Noun phrase (“Errors”, “Rate limits”)template-reference
Each template (right column) owns the required sections, naming, and frontmatter for its type. Endpoint reference is generated from OpenAPI; hand-authored reference covers only errors, limits, and states. A quickstart is a tutorial, not a separate type. Name it with a product-scoped title ("MCP quickstart") and sidebarTitle: "Quickstart" — see the quickstart naming convention in template-tutorial. A complete API doc set spans all four types plus a changelog, an OpenAPI reference, and an llms.txt entry — see the completeness bar in request-docs-from-code. When writing any page that involves authentication or API calls, document test credentials, sandbox setup, and how to avoid touching live data — do not assume readers know how to get a safe test environment. Most common mistake: writing an explanation inside a how-to. If you write “the reason this works is…” in a step-by-step guide, move it to a linked concept page.

​
Agent-layer writing rules

These apply across all four types. They cost little for human writers and pay off for machine readers.
  1. One concept per page. If the title joins two tasks with “and”, split it.
  2. Canonical terms only. No synonyms for the same object (see glossary-terminology).
  3. No pronouns for technical objects. “wait for the inbox status to become active”, not “wait for it to become active”.
  4. Explicit preconditions in a ## Before you begin block, not buried in the intro prose.
  5. Explicit success state (## What you built or ## Verify the result).
  6. Tables over prose for structured data (parameters, codes, limits, state transitions).
  7. Runnable code with ALL_CAPS placeholders — see code-examples.
  8. One action per step.
  9. State what the page does not cover, with a link to where that lives.
  10. Name any non-standard behavior loudly. Standards and RFCs are an agent’s training data; every deviation is a trap. Flag it explicitly, ideally in the heading — ## Non-standard: token response field name — and say what the standard behavior would be.
  11. Keep each page scoped to fit in an agent context window. If a single page would require more than ~8,000 tokens to load, split it into linked sub-pages. Breadth belongs in a concept page or a table of contents, not one long how-to.

​
Frontmatter

Set only title and description (plus optional Mintlify fields like sidebarTitle, icon, or tag). See formatting-guidelines. Do not add non-standard frontmatter fields — Mintlify ignores them.

​
llms.txt

The repo-root llms.txt is hand-curated. When you add, move, or rename a page, add or update its entry in the form: 
- [Page title](https://docs.zapier.com/path): type — One-sentence description written for an agent.
See contribute-docs for the maintenance workflow.

​
Worked example: Trigger Inbox section

The white-label/trigger-inbox/ set is a real reference implementation of this model:
  • what-is-trigger-inbox-api — explanation (SQS mental model, inbox states and message lifecycle as Mermaid diagrams and tables)
  • trigger-inbox-onboarding, create-trigger-inbox — tutorials (numbered ## Step N: headings, cURL/TS/Python, complete script at the end)
  • consuming-messages, manage-your-inbox — how-to (task-focused, verify steps)
  • errors — reference (HTTP codes as a table)
Concepts are defined once and linked from everywhere with deep anchors.