​

Writing standards for developer docs

These standards apply to every page on docs.zapier.com, across all sections. Apply them when writing or editing any content. Zapier developer documentation is read by engineers, partners, and technical users worldwide. Many are non-native English speakers. Some use assistive technologies. Increasingly, the reader is a coding agent driving a developer. Write for clarity, consistency, and accessibility — which serves all three at once. Agent-first bar: Before marking a page done, ask: “Could an agent build a working client from this page without a follow-up question?” If the answer is no — because a parameter’s type is missing, a response field has no meaning, a prerequisite is buried in prose, or an error has no resolution path — fix it. This is the bar, not a nice-to-have.

​

When to use

• Writing or editing any page in this repo
• Reviewing a draft before opening a merge request
• Auditing language consistency across a set of pages

For terminology (Zap, app vs integration, canonical API terms), pair this with glossary-terminology. For page structure by type, see dev-doc-types.

---

​

Voice and tone

Zapier’s developer voice is knowledgeable and conveys technical authority, while staying friendly and approachable.

• Help users solve their problems and accomplish their goals.
• Address the reader in the second person (“you”). Do not refer to Zapier as “we” outside of step-by-step walkthroughs.
• Use a friendly, conversational tone. Positive contractions like “you’ll” are fine (see the contraction rule below).
• Do not talk down to readers or waste their time.
• No marketing hype. Avoid “seamless”, “blazingly fast”, “magic”. Enthusiasm shows through specificity, not superlatives.

​

Transferable patterns worth keeping

These habits make pages clearer for humans and agents alike:

• Benefit-first opener. Lead with the payoff — what the reader’s code can now do — not “In this guide we will…”.
• Be honest about limitations. State gaps plainly and give the workaround: “Direct API governance is on the roadmap, so design your handlers to drop known-bad messages before they hit the threshold.” Never paper over a sharp edge.
• End with next steps. Close task and tutorial pages with a short “Next steps” link list.

---

​

Sentence case (everywhere)

Use sentence case for all titles and headings, in every section of the repo. Capitalize only the first word and proper nouns.

• “Set up authentication” — not “Set Up Authentication”
• “What is the Trigger Inbox API?” — not “What Is The Trigger Inbox API?”

This is repo-wide with no exceptions. When editing an older page that uses Title Case headings, convert the headings you touch to sentence case.

---

​

Negative contractions

Do not use contractions that combine a verb with “not”. They are easy to misread, especially for non-native readers. Positive contractions (“you’ll”, “you’re”, “it’s”) are fine.

---

​

Sensory language

Do not assume readers can see, hear, or interact in a specific way. Sensory-specific language excludes users with disabilities and is less precise. The most common offenders: “see” → check, review, go to; “view” → open, review; “look at” → check, examine; “watch” → follow, track; “as you can see” → notice that. accessibility-inclusivity is the authoritative source for the full sensory-language table and the rest of the accessibility standards (alt text, headings, link text, inclusive terminology). Apply it alongside this skill.

---

​

Punctuation

• No em-dashes (—). They are hard to read for some readers and signal AI-generated copy. Rewrite with a colon, parentheses, commas, or two sentences.
  • “The API returns an error — usually a 400” → “The API returns an error, usually a 400” or “The API returns an error (usually a 400).”
  • “Set the header — without it the request fails” → “Set the header. Without it, the request fails.”
• Do not substitute a double hyphen (--) for an em-dash. For a number range, use “to” (“5 to 10 minutes”) or an en-dash where a range is conventional.
• Use the serial (Oxford) comma: “triggers, searches, and actions”.

---

​

Active voice

Use active voice. It is shorter, clearer, and more direct. Passive voice is acceptable for describing platform limits or the cause of an error.

---

​

Plain language

Choose common, concrete words. Avoid jargon, noun stacks, and hedging. Noun stacks: Avoid chaining more than three nouns. “Trigger inbox subscription notification URL” → “notification URL for your inbox subscription”.

---

​

Headings

• Sentence case (see above).
• Action-oriented verb phrases for tutorials and how-tos: “Create an inbox”, “Exchange your token”.
• Noun phrases for reference and concept pages: “Authentication”, “Error codes”, “What is the Trigger Inbox API?”.
• Do not put “FAQs” in titles — surface answers in context instead.

---

​

Steps and instructions

• One action per step. Do not combine two instructions into one numbered item. If a step contains “and” or “then”, split it.
• Lead with the action verb: “Click Save”, not “You should click the Save button”.
• Use “select” for an option in a defined set; use “enter” for free-text fields.
• Bold elements the reader interacts with; italicize contextual in-app text they do not click. Use “click” for web, “tap” for mobile. Never “click on”.
• Do not rely on directional cues alone (“on the left”, “below”) — pair them with an element name.

---

​

Quick-check list

Before finalizing any page, confirm:

• Sentence case titles and headings
• 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
• No sensory language — full check via accessibility-inclusivity (see, view, look at, watch, walk through)
• Active voice (except for limits or error causes)
• No jargon or noun stacks over three words
• Second person; no marketing hype
• One action per step
• Terminology consistent with glossary-terminology
• Page ends with next steps where applicable