Skip to main content

​
Create new developer docs

Workflow for drafting a brand-new page on docs.zapier.com (public-api-docs). This skill covers research and drafting; contribute-docs 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, accessibility-inclusivity, formatting-guidelines, code-examples, glossary-terminology.

​
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: 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)
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 before drafting.

​
Step 4: Draft from the template

Create the .mdx file in the correct section folder and draft using the matching template skill: 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.
  3. Write runnable, multi-language examples per code-examples. 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 — 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. Hand-authored reference is only for errors, limits, and states.

​
Step 6: Register and finalize

Hand off to contribute-docs 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 before declaring it complete. If you identified existing pages that also need changes (Step 3), tell the user.