Request docs from code changes

Turn an engineering change into an actionable documentation request or draft for docs.zapier.com (public-api-docs). Helps PMs and engineers hand work to Tech Writing, and gives a writer a starting point.

When to use

A feature or API change is shipping and needs documentation
An MR contains developer-facing changes (endpoints, SDK methods, auth, errors)
A PM or engineer wants to flag something for Tech Writing

Completeness bar for an API

Before deciding what is missing, measure the API against what a fully documented API needs. Each is required unless noted:

Component	Covers
Quickstart	Authentication plus one working end-to-end call in under 10 minutes
Conceptual guide	What the API is, why to use it, how it fits the other primitives
API reference	Every endpoint, parameter, error, and request/response shape (generated from OpenAPI)
Code examples	Runnable, multi-language, with error handling and responses
Errors and limits	Status codes, error shapes, rate limits, quotas
Changelog	Dated, reverse-chronological, breaking changes highlighted
`llms.txt` entry	The API indexed at `docs.zapier.com/llms.txt`
Test / sandbox setup	How to get test credentials, sandbox or staging environment, and avoid touching live data — required for any API with auth
Full runnable example	End-to-end reference implementation: a single script or repo that exercises auth → core operation → success verification, with a README listing prerequisites and expected output. Required for high-traffic APIs (Trigger Inbox, MCP, Workflow API, SDK). Link from the tutorial intro. The complete-script pattern satisfies this for single-page walkthroughs.

Anything absent is a gap — use this list when producing the gap analysis (Step 4, Option C).

Step 1: Gather the change

Ask for one of:

GitLab MR or commit — read the diff and commit messages: glab mr view <ID> --output json (or gh for GitHub repos).
OpenAPI change — the spec diff is the most precise source for endpoint, parameter, and status-code changes.
Feature description — what was built, who it is for, and how it behaves.

Step 2: Map each change to a page type

For each developer-facing change, decide the documentation impact and Diataxis type (dev-doc-types):

Change	Documentation impact
New or changed endpoint	Reference is generated from OpenAPI — request spec annotations (descriptions, examples), not hand-written reference. May also need a how-to.
New SDK method or CLI command	How-to or tutorial showing real usage
New auth flow or scope	Concept (how it works) plus a how-to (set it up)
New feature or capability	Concept (“What is X?”) plus a tutorial for the first build
Changed user-facing behavior	Update the affected how-to or concept page
New errors, limits, or states	Hand-authored reference page, plus a how-to for resolution
Availability change (beta, GA, plan)	Update callouts or frontmatter `tag` on affected pages

Flag anything that touches generated content so it is fixed at the source, not hand-edited — see generated-content-safety.

Step 3: Cross-reference existing pages

Search the repo for related content (search the relevant section folder and docs.json for the feature, endpoint, or term). Decide, per page, whether it is a new page or an update to existing. Note bidirectional cross-links that the change implies.

Step 4: Produce the output

Pick the format that fits the request.

Option A — TECHWR ticket (recommended for handoff)

## Summary
[One sentence: what needs documentation]

## Feature details
- What it does: [brief description]
- Audience: [developer, partner, both]
- Source: [MR, commit, or OpenAPI link]
- Ship date: [if known]

## Documentation needed
### New pages
- [ ] [Page type]: [Title] — [scope] — [target section folder]
### Updates to existing
- [ ] [Page path]: [what changes]
### Generated content
- [ ] [Endpoint(s)]: annotate OpenAPI spec at source (no hand-written reference)

## Open questions
[Anything to confirm with eng/PM]

## Stakeholder
[Name for questions]

Option B — Draft page outline

# [Page title]   {/* page type: tutorial | how-to | concept | reference */}

## [Opening — benefit-first]
## [Prerequisites, if a how-to or tutorial]
## [Main sections per the matching template skill]
## Next steps

---
Source: [MR link] · Contact: [name]

Option C — Gap analysis

## Documentation gap analysis — [feature]
Source: [MR or OpenAPI change]

### What exists
| Page | Status | Notes |
|------|--------|-------|
| [path] | Current / Outdated | [coverage] |

### What's missing
| Gap | Priority | Suggested page type + scope |
|-----|----------|------------------------------|
| [gap] | High / Med / Low | [type + scope] |

### Recommended action
[Next step for Tech Writing]

Step 5: Hand off

To write it now: continue with create-new-dev-docs for new pages or update-existing-dev-docs for edits.
To hand off: deliver the TECHWR ticket or outline to the writer.

Create a docs request for [MR URL] What docs exist for [feature]? Draft a page outline for [feature description]

create-new-dev-docs — draft the new pages this identifies
update-existing-dev-docs — apply the updates this identifies
dev-doc-types — choose the right page type
contribute-docs — repo mechanics for landing the change

​Request docs from code changes

​When to use

​Completeness bar for an API

​Step 1: Gather the change

​Step 2: Map each change to a page type

​Step 3: Cross-reference existing pages

​Step 4: Produce the output

​Option A — TECHWR ticket (recommended for handoff)

​Option B — Draft page outline

​Option C — Gap analysis

​Step 5: Hand off

​Quick prompts to share with teams

​Related skills