> ## 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.

> [Workflow] Create a new page on docs.zapier.com from a source (a TECHWR ticket, an engineering MR or OpenAPI spec, or a feature description). Use when starting a new developer or API doc, documenting a new endpoint, SDK method, or feature. Handles research, page-type selection, drafting from a template, cross-linking, accuracy checks, and registering the page. Pairs with contribute-docs for the structural mechanics.

# SKILL

# Create new developer docs

Workflow for drafting a brand-new page on [docs.zapier.com](https://docs.zapier.com) (`public-api-docs`). This skill covers research and drafting; [contribute-docs](../contribute-docs/SKILL.md) covers the repo mechanics (docs.json, redirects, llms.txt, merge request).

## When to use

* Starting a new developer or API documentation page
* Documenting a new endpoint, SDK method, auth flow, or feature
* Drafting from a TECHWR ticket, an engineering MR or OpenAPI spec, or a feature description

Apply the foundational skills throughout: [writing-standards-dev-docs](../writing-standards-dev-docs/SKILL.md), [accessibility-inclusivity](../accessibility-inclusivity/SKILL.md), [formatting-guidelines](../formatting-guidelines/SKILL.md), [code-examples](../code-examples/SKILL.md), [glossary-terminology](../glossary-terminology/SKILL.md).

***

## Step 1: Gather the source

Start from whatever exists. Ask for one if none is given:

* **TECHWR ticket** — read the description, acceptance criteria, and linked specs.
* **Engineering MR or OpenAPI spec** — read the diff, commit messages, and schema changes. The OpenAPI spec is the source of truth for endpoint paths, parameters, and status codes.
* **Feature description** — what was built, who it is for, and how it behaves.

Capture: what the feature does, the audience (developer, partner, or both), and the exact API surface (endpoints, fields, methods).

## Step 2: Choose the page type

Decide the Diataxis type with [dev-doc-types](../dev-doc-types/SKILL.md): tutorial, how-to, reference, or explanation. One concept per page — if the source covers a task *and* the "why", that is a how-to plus a linked concept page, not one page.

A new feature often needs more than one page, for example:

* An **explanation** ("What is X?") for the model and when to use it
* A **tutorial** ("Create your first X") for the end-to-end build
* One or more **how-to** pages for specific tasks
* A **reference** page for errors, limits, or states (endpoint reference is generated from OpenAPI — see Step 5)

## Step 3: Find related pages and plan cross-links

Search the repo for existing pages on the same product area (look in the relevant section folder and `docs.json`). For each related page, decide whether it should:

* Be linked from the new page ("Next steps", "Related"), and/or
* Get a link back to the new page (bidirectional cross-linking).

Record which existing pages need a link added. If the new page introduces a new section or sub-section, plan it with [contribute-docs](../contribute-docs/SKILL.md) before drafting.

## Step 4: Draft from the template

Create the `.mdx` file in the correct section folder and draft using the matching template skill:

* [template-tutorial](../template-tutorial/SKILL.md)
* [template-how-to](../template-how-to/SKILL.md) (includes the error-handling variant)
* [template-concept](../template-concept/SKILL.md)
* [template-reference](../template-reference/SKILL.md)

Rules while drafting:

1. **Only document what the source confirms.** Do not invent endpoints, fields, or behavior to fill gaps — ask the user or mark the gap with a JSX comment (`{/* ENG QUESTION: ... */}`).
2. Add frontmatter (`title` and `description` only) per [formatting-guidelines](../formatting-guidelines/SKILL.md).
3. Write runnable, multi-language examples per [code-examples](../code-examples/SKILL.md). Validate every path, field, and status code against the OpenAPI spec.
4. Add the cross-links planned in Step 3. For a page that does not have a published URL yet, link by its intended repo path.
5. If availability is limited (beta, early access, plan-gated), surface it with a callout or frontmatter `tag` per [formatting-guidelines](../formatting-guidelines/SKILL.md) — confirm the status with the source, do not guess.

## Step 5: Respect generated content

Endpoint reference pages are generated from OpenAPI and must not be hand-authored. If the feature adds endpoints, the documentation lands by annotating the OpenAPI spec (descriptions, examples) at the source, not by writing reference `.mdx` by hand. See [generated-content-safety](../../rules/generated-content-safety.mdc). Hand-authored reference is only for errors, limits, and states.

## Step 6: Register and finalize

Hand off to [contribute-docs](../contribute-docs/SKILL.md) to:

* Register the page in `docs.json` (it does not appear in the sidebar until listed).
* Add a redirect if a URL changes, and update the committed `llms.txt`.
* Run the local preview and broken-link check, then open a merge request.

Then run [review-before-done](../review-before-done/SKILL.md) before declaring it complete. If you identified existing pages that also need changes (Step 3), tell the user.

***

## Related skills

* [contribute-docs](../contribute-docs/SKILL.md) — repo mechanics, docs.json, redirects, llms.txt, MR
* [update-existing-dev-docs](../update-existing-dev-docs/SKILL.md) — editing existing pages
* [review-before-done](../review-before-done/SKILL.md) — pre-merge quality check
* [dev-doc-types](../dev-doc-types/SKILL.md) — choose the page type