​

Tutorial template

Use this template for a tutorial: a learning-oriented page where the reader follows numbered steps and ends with something that works. Quick starts are tutorials. This is the Tutorial quadrant in dev-doc-types. A tutorial is not a how-to. A tutorial teaches a skill through a guided, linear path with no branching (“you could also…”). A how-to helps a competent reader hit a known goal. If the reader already knows what they want and just needs the steps, write a how-to instead.

​

When to use

• A quick start (“Make your first API call”)
• A first end-to-end build (“Create your first trigger inbox”)
• Onboarding a reader to a product area through a worked example

​

Always apply

Apply all Foundational skills as you write — writing standards, accessibility, formatting, code examples, terminology. See SKILLS-INDEX.

​

Template location

assets/template-tutorial.mdx — structure and placeholders only. All writing rules live in this SKILL.md.

---

​

Required sections (in order)

​

Writing the intro

• Lead with what the reader’s code can do at the end, not “In this tutorial we will…”.
• Keep it to one or two sentences.
• If the tutorial is long, link to the complete script: “In a hurry? Skip to the complete script.”

​

Writing steps

• One action per step. If a step contains “and” or “then”, split it.
• Start each step heading with a verb: ## Step 1: Create an inbox. Do not put “Step 1:” in the page title.
• Every step that involves an API call or SDK method needs a runnable <CodeGroup> example (cURL → TypeScript → Python).
• Carry values between steps with environment variables (export INBOX_ID=...), per code-examples.
• State the expected result after the action (“The response includes the new inbox_id.”), so the reader can confirm they are on track.
• Keep the path linear. Move alternatives and edge cases into an <Accordion> or a linked how-to.

​

Naming

• Title is a verb phrase describing the outcome: “Create your first trigger inbox”, “Make your first API call”.
• Do not name it “Tutorial” or put “Step 1” in the title.

​

Quickstart pages

A quickstart is the fast, getting-started tutorial for a product or feature. Name every quickstart the same way so they are consistent in the sidebar and unique to search and agents:

• Spelling: one word, “Quickstart” (not “Quick start” or “quick-start”).
• title: always scope it to the product or feature so the page is unique across sections. Use either "<Product> quickstart" (for example "MCP quickstart", "Trigger Inbox quickstart") or a verb phrase that names the product ("Connect your AI to Zapier MCP"). Never a bare "Quickstart", which collides across sections.
• sidebarTitle: always "Quickstart", so the nav stays short and scannable.
• description: state the task, with a time-to-value cue where it is honest (for example “Connect a web AI agent to Zapier MCP in under 5 minutes.”).
• Update the page’s llms.txt entry so its label matches the title.
• Prefer “quickstart” over “onboarding” for these pages: “onboarding” is ambiguous and collides with partner onboarding.

​

Frontmatter

Set only title and description (see formatting-guidelines). List prerequisites in the ## Before you begin body section, not in frontmatter.

​

Before you finish

Register the page in docs.json and update llms.txt (contribute-docs), then run review-before-done.