Skip to main content

​
Review before done

Rigorous self-review for developer documentation on docs.zapier.com (public-api-docs). Never declare done until validated.

​
When to use

  • User says “review this”, “check my work”, or “is this ready to merge?”
  • After finishing a draft or update — proactively offer: “Want me to run the review checklist before we call this done?”
  • When choosing a page type or structure: “Which approach is safer?”
Related: Use this at the end of create-new-dev-docs and update-existing-dev-docs, or any time the user wants a quality check.

​
Core principles

  1. Never declare done until validated. Run the checklist and the build/link checks, or document why a step was skipped.
  2. Accuracy is non-negotiable. Every endpoint, field, parameter, and status code must match the OpenAPI spec. Every code example must run. Do not invent API surface — verify it or flag the gap.
  3. Assumptions are bugs. When information is missing, ask the user or mark it with a JSX comment, do not guess.
  4. The reader is also an agent. The bar: a coding agent could build a working client from the page without asking a follow-up question. When it cannot, fix the page, not the prompt.
  5. Pragmatism over perfectionism. Accept justified tradeoffs and document them. Do not block on minor style if the page is correct and usable.
Security (content): No hardcoded secrets, real tokens, or API keys in examples — use obvious placeholders. No internal-only URLs in published copy. Always flag these.

​
Calibration by stakes

StakesExamplesReview depth
HighNew product/feature page, auth or security content, first use of a template, anything an agent will follow to write codeFull checklist, verify accuracy against OpenAPI, verify build and links
MediumRoutine update, new how-to, multi-page changeCore checklist, spot-check accuracy and links
LowTypo, formatting-only, internal noteQuick scan; flag security and accuracy issues only
When unsure: Ask “Is this merging soon or still a draft? I’ll calibrate.”

​
Doc review checklist

​
Accuracy and security

  • Endpoints, fields, parameters, and status codes match the OpenAPI spec
  • Code examples run as written and follow code-examples (multi-language via CodeGroup where expected)
  • No hardcoded secrets, real tokens, or API keys — only obvious placeholders
  • No internal-only URLs in published copy
  • No invented behavior — gaps are flagged with the user or a JSX comment, not filled
  • Agent-readiness (high-stakes pages): point an agent at the page and ask it to implement against it; if it needs a follow-up question, fix the page (not the prompt)

​
Writing standards

Run the full quick-check list in writing-standards-dev-docs. Highest-value scans:
  • Sentence case titles and headings (no Title Case)
  • No negative contractions (don’t, can’t, won’t, isn’t, shouldn’t…)
  • No em-dashes (—) — rewrite with a colon, parentheses, commas, or two sentences
  • One action per step; terminology consistent with glossary-terminology

​
Accessibility and inclusivity

Run the full quick-check list in accessibility-inclusivity. Highest-value scans:
  • No sensory language (see, view, look at, watch, walk through)
  • Meaningful alt text; no required information lives only in an image
  • Link text describes its destination (no “click here”)
  • Inclusive terminology (allowlist/denylist, main/replica, they)

​
Structure and formatting

​
Structure mechanics (when URLs or navigation change)

Per contribute-docs:
  • New page registered in docs.json (it will not appear in the sidebar otherwise)
  • redirects entry added for any moved, renamed, consolidated, or removed page
  • Internal links to old paths updated
  • Committed llms.txt updated for any added, moved, renamed, or removed page

​
Generated content

  • No hand-edits to generated files (endpoint reference, snippets/sdk/*, integration checks reference, news.mdx) — changes made at the source per generated-content-safety
  • Local preview checked (pnpm run dev)
  • Broken-link check run (pnpx mintlify broken-links)
  • Full build passes where appropriate (pnpm run build)

​
Ship-it criteria

Say explicitly when you are satisfied. Sign off when:
  • Accuracy verified (or gaps flagged for the user)
  • No critical content/security issues (or tradeoffs documented)
  • Structure mechanics done or intentionally deferred with a reason
  • Build and link checks pass (or are deferred with a reason)
Do not block on: perfect prose, every edge case, or extremely unlikely scenarios. Verdict:
  • 4/4: “Ship it.”
  • 3/4: “Ship it, but watch [specific thing].”
  • 2/4 or less: “Not ready. Here’s what needs fixing: [list].”

​
Review action protocol

Do not just list problems — fix and verify:
  1. Identify — list what could be wrong (checklist items, links, accuracy).
  2. Verify — spot-check against the OpenAPI spec and run the link check.
  3. Fix — make the changes.
  4. Validate — re-run the check that failed.
  5. Document — explain what was wrong and why the fix is correct.

​
If the user repeatedly ignores the same concern

  • First time: full explanation. Second: brief reminder. Third: note and move on. Fourth+: stop mentioning it.
  • Exception: content/security issues (secrets, internal URLs, wrong API surface) — always flag, every time.