> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapier.com/llms.txt
> Use this file to discover all available pages before exploring further.

> [Reference] How to choose and structure a developer doc page using the Diataxis model plus an agent-readability layer. Covers the four page types (tutorial, how-to, reference, explanation), their required sections and frontmatter, the agent-layer writing rules, and llms.txt. Use when deciding what kind of page to write, structuring a new page, or restructuring an existing one.

# SKILL

# 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](../writing-standards-dev-docs/SKILL.md).

This structure follows the [Diataxis framework](https://diataxis.fr) — 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)
```

| Type                                 | Primary question                              | Title style                           | Template (owns the full schema)                      |
| ------------------------------------ | --------------------------------------------- | ------------------------------------- | ---------------------------------------------------- |
| Tutorial                             | "How do I get something working?"             | Verb phrase ("Create your first…")    | [template-tutorial](../template-tutorial/SKILL.md)   |
| How-to (task, troubleshooting)       | "How do I do or fix this specific thing?"     | Verb phrase ("Manage your inbox")     | [template-how-to](../template-how-to/SKILL.md)       |
| Explanation (concept)                | "What is this and why does it work this way?" | Noun phrase ("What is …?")            | [template-concept](../template-concept/SKILL.md)     |
| Reference (errors, limits, glossary) | "What exactly does this mean or do?"          | Noun phrase ("Errors", "Rate limits") | [template-reference](../template-reference/SKILL.md) |

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](../template-tutorial/SKILL.md).

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](../request-docs-from-code/SKILL.md). 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](../glossary-terminology/SKILL.md)).
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](../code-examples/SKILL.md).
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](../formatting-guidelines/SKILL.md). 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](../contribute-docs/SKILL.md) 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.

***

## Related

* [writing-standards-dev-docs](../writing-standards-dev-docs/SKILL.md) — voice, headings, steps
* [accessibility-inclusivity](../accessibility-inclusivity/SKILL.md) — sensory-neutral and inclusive language
* [formatting-guidelines](../formatting-guidelines/SKILL.md) — components and frontmatter
* [code-examples](../code-examples/SKILL.md) — runnable, multi-language examples
* Templates per type: [template-tutorial](../template-tutorial/SKILL.md), [template-how-to](../template-how-to/SKILL.md) (error-handling variant), [template-concept](../template-concept/SKILL.md), [template-reference](../template-reference/SKILL.md)