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
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.
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.
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:
`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.
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.
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.
Close with the one behavior fact a reader needs, in one or two
sentences: cache key, invalidation trigger, timeout.
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.
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:
- 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.
- 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.
- 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.
- 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.
- 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:
- Name what it is.
<Subject> is a(n) <category>.
- 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."
- 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).
1---2name: writing-reference-docs3description: >-4 How to write a function/hook/action reference section, and how to write or5 rework a whole app's multi-page doc set (Overview/Features/Talk to the6 Agent/Cross-App Use/Developer Guide): plain-language signature, real7 arguments, escalating examples grounded in a real app, verified agent8 behavior, trimmed prose with no em dashes or semicolons. Use when writing or9 editing a packages/core/docs/content reference page, or reworking a10 template-<app>*.mdx doc set.11scope: dev12metadata:13 source: https://skillmd.com/skills/builderio/writing-reference-docs14 internal: true15---1617# Writing Reference Docs1819This came out of rewriting `client-data.mdx`'s hook sections20(`useActionQuery`, `useActionMutation`, `callAction`, `useDbSync`) section by21section with the user. It captures the shape that emerged so the next22reference section starts from it instead of reinventing it.2324## Rule2526Document each function, hook, or action reference as: a plain-language27purpose statement, a bulleted argument list matching the real signature, two28or more escalating runnable examples grounded in a real app, and a one or two29sentence closing behavior note. Never a bare one-line description with a30single toy snippet.3132## Why3334The original `client-data.mdx` gave each hook one sentence and one minimal35snippet with no options argument shown at all. That hid real, common needs36(conditional fetching via `enabled`, a post-mutation side effect via37`onSuccess`) that readers would only discover by reading the source. It also38leaned on a hypothetical `leads` domain (`get-lead`, `create-lead`,39`archive-lead`) that reads as unconvincing next to an example grounded in a40real app with a real schema and real access rules.4142## How43441. **Match heading level to role.** Hooks that solve the same kind of problem45 get grouped under one parent heading (e.g. `### Action hooks`) with each46 hook as a child heading below it. A utility that is not a hook (like47 `callAction`) is a sibling heading at the same level as the group, not a48 child of it, even if it lives right next to the group.492. **Open with plain-language purpose, then link out.** State what the50 function is for in one or two sentences ("This hook is intended to be used51 for..."). If it wraps another library's hook (React Query's `useQuery`,52 `useMutation`), link its reference page instead of re-documenting fields53 you don't own.543. **List real arguments as a short bullet list**, matching the actual55 exported signature in `packages/core/src/client/`, not a paraphrase. Read56 the source before writing the list. Skip the bullet-list format entirely57 for a function that takes only one argument. Fold that into a sentence58 instead:5960 ```md61 `useActionQuery()` accepts three arguments:6263 - **actionName**: the action's registered name.64 - **params**: the action's input, typed from its `defineAction()` schema.65 - **options**: everything from the [useQuery options](...) except66 `queryKey` and `queryFn`, which the hook sets itself.67 ```68694. **Give two or more escalating examples.** The first is the simplest70 possible call. The second demonstrates one real, common option (a71 conditional fetch, a success callback, a longer timeout), with one72 sentence before it explaining what's different and why it matters.735. **Ground every example in a real reference app's real action**, not an74 invented one, e.g. `get-ticket`, `send-ticket-reply`, `update-ticket` from75 a real ticket-support example app, rather than `get-lead`/`create-lead`.76 Exception: if the page already threads a hypothetical domain across77 multiple sibling pages (a running example), keep using that domain in this78 page too. Enrich its snippets with the missing option; don't swap the79 domain out from under the other pages.806. **Close with the one behavior fact a reader needs**, in one or two81 sentences: cache key, invalidation trigger, timeout.827. **Prose rules, every sentence:** no em dashes, no semicolons (this83 includes table cells), short sentences. Split into two sentences instead84 of joining with either. Reference every function by name with parens,85 `useActionQuery()` not `useActionQuery`.868. **Example values must mean something to a reader with zero app context.**87 Don't reuse an in-app sentinel value (like a `"me"` string a real action88 resolves specially) without explaining it. Use a literal, self-explanatory89 value instead, like a real-looking email address.9091## Don't9293- Don't introduce a new framework concept into the primary example just94 because it's technically correct for that hook. If most readers of this95 page will never need to write it themselves (e.g. wiring `ignoreSource` with96 a per-tab id), it belongs in the options table, not the main example, or on97 a deeper page like Advanced.98- Don't swap a page's running example domain without checking whether sibling99 pages share it. Grep the other draft pages for the same domain terms first.100- Don't leave a semicolon or em dash anywhere in the page, including table101 cells. Split into two sentences.102- Don't add a one-item options bullet list for a function that only takes a103 single argument. State it in a sentence instead.104- Don't paraphrase a signature from memory. Grep the actual export in105 `packages/core/src/client/` and read its real parameter and option types.106107## App Doc Format (apps only)108109This is a second, related pattern this skill covers: writing or reworking a110whole app's doc set under `packages/core/docs/content/template-<app>*.mdx`,111not a single function/hook/action reference section. It came out of reworking112Forms' docs (`template-forms*.mdx`) to match the shape Calendar's docs113(`template-calendar*.mdx`) had already established. It does not apply to a114standalone reference page like `client-data.mdx`.115116### The five pages117118An app's docs are five pages, in this order:1191201. **Overview** (`template-<app>.mdx`) — marketing-level. What the app does, a121 "What it replaces" comparison, a short multi-app-workspace teaser linking122 to Cross-App Use, and a "What you can do with it" list linking into123 Features. No feature depth, no setup steps.1242. **Features** (`template-<app>-features.mdx`) — every feature area a user125 would actually use, ordered the way someone would approach the app (build,126 then publish, then protect, then analyze, then route), with127 `Steps`/`Callout`/`Table`/`Diagram` for how to set each one up.1283. **Talk to the Agent** (`template-<app>-agent.mdx`) — how the agent sees the129 user's screen, grounded in the app's real `view-screen`/`navigate` actions130 and application-state keys, then prompts by task in a `Cards` grid.1314. **Cross-App Use** (`template-<app>-integrations.mdx`) — how the app132 connects to Dispatch (the "same workspace: automatic" / "separate133 deployments: one manual step" split is generic framework behavior,134 identical across apps), then the app's own real cross-app mechanisms.1355. **Developer Guide** (`template-<app>-developers.mdx`) — quick start, an136 action reference table by category, the data model, an action walked137 through, a routes-reference `FileTree`, and how to customize it.138139Calendar's docs are the reference implementation. Read them before writing the140equivalent page for another app.141142### Match the audience to the page tier143144Overview, Features, Talk to the Agent, and Cross-App Use are for an145interested but non-technical reader. Don't assume prior knowledge of the146framework's own vocabulary (SQL-backed, unauthenticated, endpoint, action) and147prefer plain equivalents ("the same form" instead of "the same SQL-backed form148definition"). Developer Guide is for developers: SQL, schemas, and action149names belong there, not on the earlier four pages.150151### Don't force a section that doesn't apply152153Calendar has capabilities other apps may not: a real `ExtensionSlot`154(documented in its own Talk to the Agent page), and a live external provider155(Google Calendar) it can escalate to with a raw API call. Before copying156either section into another app's docs, verify the app actually has the157underlying capability (grep for `ExtensionSlot` usage, grep for158`registerEvent`/`emit` calls or provider-API actions). If it doesn't, omit the159section entirely rather than writing around a capability that isn't there.160The goal is mirroring the *format*, not force-fitting content Calendar happens161to have.162163### An action walked through (Developer Guide only)164165Show the real source of one real action file, with `AnnotatedCode` line-range166annotations pointing at actual line numbers in that pasted source. Don't167synthesize a CLI invocation example instead. Pick an action with a genuinely168reusable pattern (a concurrency lock, a two-table uniqueness check, input169normalization), not just the simplest one.170171## Voice: Declarative, Not Imperative172173Applies broadly, to any docs page, reference section or app page alike. It174came out of reworking Slides' Overview intro paragraph, which opened "Generate175full presentation decks from a prompt, edit slides visually, and present176full-screen" — accurate, but a bare imperative verb with no stated subject177reads as ad copy, not documentation, and invites hype words like "in seconds"178or "own end to end" that don't add information.179180State the subject first: what the thing *is*, then what happens when you use181it. Calendar's Overview opening is the reference shape: "Calendar is an182agent-powered scheduling app. Connect your Google Calendar and the agent can183read your schedule, find free time, create events, and manage Calendly-style184booking links, in plain English or with a click. It replaces the Google185Calendar + Calendly combo with one app, so your real schedule and your public186booking pages are never two things you have to keep in sync by hand." Three187moves, in order:1881891. **Name what it is.** `<Subject> is a(n) <category>.`1902. **One sentence of what using it looks like.** A trigger clause followed by191 what the agent then does, e.g. "...and the agent can `<verb list>`, in192 plain English or with a click."1933. **What it replaces, and why that's better.** "It replaces `<X>` with one194 app, so `<concrete benefit>`."195196An imperative clause is fine inside that shape ("Connect your Google Calendar197and the agent can...") because it's conditional, not a command aimed at the198reader as the paragraph's opener. The same two-sentence shape (declarative199opener, then a capability-list sentence) applies to the frontmatter200`description` field too. Apply this to the free-flowing prose paragraphs on a201page (the opening paragraph, teaser paragraphs, closing behavior notes). It202does not apply to procedural instructions (numbered setup steps genuinely are203commands), quoted example prompts (they're user speech, not framework prose),204or the bold-imperative-lead bullet convention used for feature lists205("**Build forms conversationally.** Try prompts like...") since that's an206established, distinct list convention across the doc set, not a tone problem.207208## Verify Agent-Driven Claims209210Applies broadly, to any docs page, reference section or app page alike.211Before writing that a prompt or an agent action "does X," confirm it actually212does, ideally by running the real action against the real app rather than213inferring behavior from reading the action's code or its `description` field214alone. Two things this catches that a code read alone won't: a missing215runtime prerequisite (an action implemented correctly but that throws because216a dependency like file storage isn't configured), and a claim that's flatly217untrue (an action that doesn't exist for what the doc describes, like "turn on218spam protection" when spam-protection keys are an app-wide Settings field with219no action that sets them). When a claim doesn't hold up, don't soften it into220a hedge. Either fix the doc to describe what's real, or cut the claim.221222## Retiring or Merging a Doc Page223224Applies broadly, to any page under `packages/core/docs/content`. Add the old225slug to `DOCS_SLUG_REDIRECTS` in226`packages/docs/app/components/docs-slug-redirects.ts` (a plain slug-to-slug227map, dependency-free, checked by `packages/docs/tests/redirects.test.ts`)228before deleting the old `.mdx` file. Don't leave a merged or renamed page229without a redirect entry, or the old URL just 404s.230231## Localizing a Docs Restructuring232233Applies broadly, to any page under `packages/core/docs/content`.234`pnpm guard:i18n-catalogs` checks three separate things after a docs235restructuring, and each needs a different fix:236237- A nav label added or removed in `packages/docs/app/i18n/en-US.ts` (e.g. a238 new page's sidebar entry) needs the same key added or removed in every239 other locale file under `packages/docs/app/i18n/`. Reuse an existing240 sibling app's translation for the same concept (e.g. Calendar's241 `calendarFeatures`) instead of coining a new one.242- A source doc that changed meaningfully needs its locale copies under243 `content/locales/*` updated too, or the doc-coverage gap recorded as244 reviewed debt via `UPDATE_I18N_DOC_COVERAGE_BASELINE=1 pnpm245 guard:i18n-catalogs`. Diff the baseline file afterward to confirm it only246 changed the entries you expected.247- A short technical fragment (a diagram label, a product name) that's248 legitimately identical across languages (a shared loanword, a proper noun)249 isn't a translation gap. Add it to `scripts/i18n-no-translate-terms.txt`250 instead of forcing an artificial difference, but only after confirming that251 other locales which DID translate the surrounding text also left this exact252 fragment alone, not that it was simply missed.253254## Related Skills255256- **writing-agent-instructions** — the sibling guide for AGENTS.md/SKILL.md257 prose, which this borrows its "say it once, plainly" spirit from.258- **agent-native-docs** — how to look up the version-matched docs this skill259 helps you write.260- **internationalization** — localized copies under `content/locales/*` need261 the same edit when a source doc's meaning changes (see CLAUDE.md and262 "Localizing a Docs Restructuring" above for the guard/baseline mechanics).