writing-reference-docs

name	writing-reference-docs
description	How to write a function/hook/action reference section: plain-language signature, real arguments, escalating examples grounded in a real app, trimmed prose with no em dashes or semicolons. Use when writing or editing a packages/core/docs/content reference page.
scope	dev
metadata	{"internal":true}

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, , ) that reads as unconvincing next to an example grounded in a real app with a real schema and real access rules.