Skip to main content

​
Update existing developer docs

Workflow for changing a page that already exists on docs.zapier.com (public-api-docs). This skill covers finding and editing; contribute-docs covers the repo mechanics.

​
When to use

  • Fixing outdated or incorrect developer or API content
  • Reflecting an API, SDK, auth, or product change
  • Restructuring a page for clarity or to match its page type
Apply the foundational skills throughout: writing-standards-dev-docs, accessibility-inclusivity, formatting-guidelines, code-examples, glossary-terminology.

​
Step 1: Gather the source

Start from the change driver: a TECHWR ticket, an engineering MR or OpenAPI change, or a reported inaccuracy. Capture exactly what changed in the product, and the affected API surface. The OpenAPI spec is the source of truth for endpoints, fields, and status codes.

​
Step 2: Locate the affected pages

Search the repo for the relevant content (search the section folder and docs.json for the feature, endpoint, or term). Then:
  1. Read each candidate page for content that is now incorrect, missing, or unclear.
  2. Identify the page’s Diataxis type and compare it to its template (template-tutorial, template-how-to, template-concept, template-reference). Note any missing or misplaced sections — for example, an explanation that has crept into a how-to belongs on a linked concept page.
  3. Check sibling and related pages in the same section: are they affected by the same change?
  4. Record cross-links that need adding, fixing, or removing if the update changes scope or “what to read next”.

​
Step 3: Edit in place with diffs

Edit directly in the existing .mdx file:
  1. Only use information from the page or the source. Do not invent details to fill gaps — ask the user, or mark the gap with a JSX comment ({/* ENG QUESTION: ... */}).
  2. Present changes as reviewable diffs.
  3. Re-verify every endpoint path, field name, and status code against the OpenAPI spec. Confirm code examples still run and follow code-examples.
  4. Convert any Title Case headings you touch to sentence case, and apply the other writing standards as you go.
  5. Add or fix the cross-links recorded in Step 2 — in both the page you are editing and the related pages.
  6. If availability changed (for example, beta to GA), update or remove the callout or frontmatter tag accordingly.

​
Step 4: Respect generated content

If the change affects endpoint reference, fix it at the source (the OpenAPI spec annotations), not in a generated .mdx. The same applies to snippets/sdk/* and other generated files. See generated-content-safety.

​
Step 5: Handle URL changes and finalize

If the update moves, renames, consolidates, or removes a page so its URL changes, hand off to contribute-docs to add the redirect, update docs.json, fix internal links to the old path, and update the committed llms.txt. Run the local preview and broken-link check, then open a merge request. Run review-before-done before declaring it complete. If you found content that should be a new page rather than an edit (Step 2), tell the user.