writing-reference-docs

# Writing Reference Docs This came out of rewriting `client-data.mdx`'s hook sections (`useActionQuery`, `useActionMutation`, `callAction`, `useDbSync`) section by section with the user. It captures the shape that emerged so the next reference section starts from it instead of reinventing it. ## Rule Document each function, hook, or action reference as: a plain-language purpose statement, a bulleted argument list matching the real signature, two or more escalating runnable examples grounded in a real app, and a one or two sentence closing behavior note. Never a bare one-line description with a single toy snippet. ## Why The original `client-data.mdx` gave each hook one sentence and one minimal snippet with no options argument shown at all. That hid real, common needs (conditional fetching via `enabled`, a post-mutation side effect via `onSuccess`) that readers would only discover by reading the source. It also leaned on a hypothetical `leads` domain (`get-lead`, `create-lead`, `archive-lead`) that reads as unconvincing next to an example grounded in a real app with a real schema and real access rules. ## How 1. **Match heading level to role.** Hooks that solve the same kind of problem get grouped under one parent heading (e.g. `### Action hooks`) with each hook as a child heading below it. A utility that is not a hook (like `callAction`) is a sibling heading at the same level as the group, not a child of it, even if it lives right next to the group. 2. **Open with plain-language purpose, then link out.** State what the function is for in one or two sentences ("This hook is intended to be used for..."). If it wraps another library's hook (React Query's `useQuery`, `useMutation`), link its reference page instead of re-documenting fields you don't own. 3. **List real arguments as a short bullet list**, matching the actual exported signature in `packages/core/src/client/`, not a paraphrase. Read the source before writing the list. Skip the bullet-list format entirely for a function that takes only one argument. Fold that into a sentence instead: ```md `useActionQuery()` accepts three arguments: - **actionName**: the action's registered name. - **params**: the action's input, typed from its `defineAction()` schema. - **options**: everything from the [useQuery options](...) except `queryKey` and `queryFn`, which the hook sets itself. ``` 4. **Give two or more escalating examples.** The first is the simplest possible call. The second demonstrates one real, common option (a conditional fetch, a success callback, a longer timeout), with one sentence before it explaining what's different and why it matters. 5. **Ground every example in a real reference app's real action**, not an invented one, e.g. `get-ticket`, `send-ticket-reply`, `update-ticket` from a real ticket-support example app, rather than `get-lead`/`create-lead`. Exception: if the page already threads a hypothetical domain across multiple sibling pages (a running example), keep using that domain in this page too. Enrich its snippets with the missing option; don't swap the domain out from under the other pages. 6. **Close with the one behavior fact a reader needs**, in one or two sentences: cache key, invalidation trigger, timeout. 7. **Prose rules, every sentence:** no em dashes, no semicolons (this includes table cells), short sentences. Split into two sentences instead of joining with either. Reference every function by name with parens, `useActionQuery()` not `useActionQuery`. 8. **Example values must mean something to a reader with zero app context.** Don't reuse an in-app sentinel value (like a `"me"` string a real action resolves specially) without explaining it. Use a literal, self-explanatory value instead, like a real-looking email address. ## Don't - Don't introduce a new framework concept into the primary example just because it's technically correct for that hook. If most readers of this page will never need to write it themselves (e.g. wiring `ignoreSource` with a per-tab id), it belongs in the options table, not the main example, or on a deeper page like Advanced. - Don't swap a page's running example domain without checking whether sibling pages share it. Grep the other draft pages for the same domain terms first. - Don't leave a semicolon or em dash anywhere in the page, including table cells. Split into two sentences. - Don't add a one-item options bullet list for a function that only takes a single argument. State it in a sentence instead. - Don't paraphrase a signature from memory. Grep the actual export in `packages/core/src/client/` and read its real parameter and option types. ## App Doc Format (apps only) This is a second, related pattern this skill covers: writing or reworking a whole app's doc set under `packages/core/docs/content/template-<app>*.mdx`, not a single function/hook/action reference section. It came out of reworking Forms' docs (`template-forms*.mdx`) to match the shape Calendar's docs (`template-calendar*.mdx`) had already established. It does not apply to a standalone reference page like `client-data.mdx`. ### The five pages An app's docs are five pages, in this order: 1. **Overview** (`template-<app>.mdx`) — marketing-level. What the app does, a "What it replaces" comparison, a short multi-app-workspace teaser linking to Cross-App Use, and a "What you can do with it" list linking into Features. No feature depth, no setup steps. 2. **Features** (`template-<app>-features.mdx`) — every feature area a user would actually use, ordered the way someone would approach the app (build, then publish, then protect, then analyze, then route), with `Steps`/`Callout`/`Table`/`Diagram` for how to set each one up. 3. **Talk to the Agent** (`template-<app>-agent.mdx`) — how the agent sees the user's screen, grounded in the app's real `view-screen`/`navigate` actions and application-state keys, then prompts by task in a `Cards` grid. 4. **Cross-App Use** (`template-<app>-integrations.mdx`) — how the app connects to Dispatch (the "same workspace: automatic" / "separate deployments: one manual step" split is generic framework behavior, identical across apps), then the app's own real cross-app mechanisms. 5. **Developer Guide** (`template-<app>-developers.mdx`) — quick start, an action reference table by category, the data model, an action walked through, a routes-reference `FileTree`, and how to customize it. Calendar's docs are the reference implementation. Read them before writing the equivalent page for another app. ### Match the audience to the page tier Overview, Features, Talk to the Agent, and Cross-App Use are for an interested but non-technical reader. Don't assume prior knowledge of the framework's own vocabulary (SQL-backed, unauthenticated, endpoint, action) and prefer plain equivalents ("the same form" instead of "the same SQL-backed form definition"). Developer Guide is for developers: SQL, schemas, and action names belong there, not on the earlier four pages. ### Don't force a section that doesn't apply Calendar has capabilities other apps may not: a real `ExtensionSlot` (documented in its own Talk to the Agent page), and a live external provider (Google Calendar) it can escalate to with a raw API call. Before copying either section into another app's docs, verify the app actually has the underlying capability (grep for `ExtensionSlot` usage, grep for `registerEvent`/`emit` calls or provider-API actions). If it doesn't, omit the section entirely rather than writing around a capability that isn't there. The goal is mirroring the *format*, not force-fitting content Calendar happens to have. ### An action walked through (Developer Guide only) Show the real source of one real action file, with `AnnotatedCode` line-range annotations pointing at actual line numbers in that pasted source. Don't synthesize a CLI invocation example instead. Pick an action with a genuinely reusable pattern (a concurrency lock, a two-table uniqueness check, input normalization), not just the simplest one. ## Voice: Declarative, Not Imperative Applies broadly, to any docs page, reference section or app page alike. It came out of reworking Slides' Overview intro paragraph, which opened "Generate full presentation decks from a prompt, edit slides visually, and present full-screen" — accurate, but a bare imperative verb with no stated subject reads as ad copy, not documentation, and invites hype words like "in seconds" or "own end to end" that don't add information. State the subject first: what the thing *is*, then what happens when you use it. Calendar's Overview opening is the reference shape: "Calendar is an agent-powered scheduling app. Connect your Google Calendar and the agent can read your schedule, find free time, create events, and manage Calendly-style booking links, in plain English or with a click. It replaces the Google Calendar + Calendly combo with one app, so your real schedule and your public booking pages are never two things you have to keep in sync by hand." Three moves, in order: 1. **Name what it is.** `<Subject> is a(n) <category>.` 2. **One sentence of what using it looks like.** A trigger clause followed by what the agent then does, e.g. "...and the agent can `<verb list>`, in plain English or with a click." 3. **What it replaces, and why that's better.** "It replaces `<X>` with one app, so `<concrete benefit>`." An imperative clause is fine inside that shape ("Connect your Google Calendar and the agent can...") because it's conditional, not a command aimed at the reader as the paragraph's opener. The same two-sentence shape (declarative opener, then a capability-list sentence) applies to the frontmatter `description` field too. Apply this to the free-flowing prose paragraphs on a page (the opening paragraph, teaser paragraphs, closing behavior notes). It does not apply to procedural instructions (numbered setup steps genuinely are commands), quoted example prompts (they're user speech, not framework prose), or the bold-imperative-lead bullet convention used for feature lists ("**Build forms conversationally.** Try prompts like...") since that's an established, distinct list convention across the doc set, not a tone problem. ## Verify Agent-Driven Claims Applies broadly, to any docs page, reference section or app page alike. Before writing that a prompt or an agent action "does X," confirm it actually does, ideally by running the real action against the real app rather than inferring behavior from reading the action's code or its `description` field alone. Two things this catches that a code read alone won't: a missing runtime prerequisite (an action implemented correctly but that throws because a dependency like file storage isn't configured), and a claim that's flatly untrue (an action that doesn't exist for what the doc describes, like "turn on spam protection" when spam-protection keys are an app-wide Settings field with no action that sets them). When a claim doesn't hold up, don't soften it into a hedge. Either fix the doc to describe what's real, or cut the claim. ## Retiring or Merging a Doc Page Applies broadly, to any page under `packages/core/docs/content`. Add the old slug to `DOCS_SLUG_REDIRECTS` in `packages/docs/app/components/docs-slug-redirects.ts` (a plain slug-to-slug map, dependency-free, checked by `packages/docs/tests/redirects.test.ts`) before deleting the old `.mdx` file. Don't leave a merged or renamed page without a redirect entry, or the old URL just 404s. ## Localizing a Docs Restructuring Applies broadly, to any page under `packages/core/docs/content`. `pnpm guard:i18n-catalogs` checks three separate things after a docs restructuring, and each needs a different fix: - A nav label added or removed in `packages/docs/app/i18n/en-US.ts` (e.g. a new page's sidebar entry) needs the same key added or removed in every other locale file under `packages/docs/app/i18n/`. Reuse an existing sibling app's translation for the same concept (e.g. Calendar's `calendarFeatures`) instead of coining a new one. - A source doc that changed meaningfully needs its locale copies under `content/locales/*` updated too, or the doc-coverage gap recorded as reviewed debt via `UPDATE_I18N_DOC_COVERAGE_BASELINE=1 pnpm guard:i18n-catalogs`. Diff the baseline file afterward to confirm it only changed the entries you expected. - A short technical fragment (a diagram label, a product name) that's legitimately identical across languages (a shared loanword, a proper noun) isn't a translation gap. Add it to `scripts/i18n-no-translate-terms.txt` instead of forcing an artificial difference, but only after confirming that other locales which DID translate the surrounding text also left this exact fragment alone, not that it was simply missed. ## Related Skills - **writing-agent-instructions** — the sibling guide for AGENTS.md/SKILL.md prose, which this borrows its "say it once, plainly" spirit from. - **agent-native-docs** — how to look up the version-matched docs this skill helps you write. - **internationalization** — localized copies under `content/locales/*` need the same edit when a source doc's meaning changes (see CLAUDE.md and "Localizing a Docs Restructuring" above for the guard/baseline mechanics).