Technical writing
Help readers choose, try, install and adapt a component—with enough depth to trust what they copy.
Download the technical writing skill. Use it to research, write and review component documentation.
Write for a capable reader
Write only what helps the reader choose, build or troubleshoot. Remove repetition and explanations the preview already provides. Start with the reader's task. Use familiar words, consistent names and a small working example. Explain an unfamiliar term once or link its definition. Keep the common path easy to scan and deeper contracts easy to find. Avoid “simply”, “obviously” and unsupported claims such as “fully accessible”.
A reader may know design and be new to React, or know React and be new to this interaction. Show the result, then explain how to change it. Precision and friendliness can coexist.
Research before drafting
Read the current public source, styles, direct demos and registry/package metadata. Inventory real parts, prop values/defaults, labels, state ownership and dependencies. Compare the closest Ghost alternatives. Consult current upstream behavior documentation where relevant; another library's API does not prove Ghost supports it.
Give each section one job
Use this sequence. Keep useful old anchor links when a heading changes.
| Section | Reader question | Include |
|---|---|---|
| Preview | Is this the thing I need? | One recognizable working task |
| Design guidance, when useful | Why choose it, and how should I compose it? | Consequential alternatives, content and accessibility decisions |
| Installation | How do I obtain working source? | Actual item, shared setup link and unusual dependencies |
| Basic usage | What is the smallest usable composition? | Current import, required parts, label and minimal state/data |
| Structures | Which public parts belong where? | Real nesting, required/optional regions and caller content |
| Examples | How does this choice change the result? | One meaningful decision/state, working preview and exact source |
| API reference | What does the contract accept and do? | Exact types/defaults, requiredness, callback semantics and ownership |
Design guidance
Write a decision aid, not praise. “Use Checkbox for independent choices; use RadioGroup when one option must be chosen; use Switch for an immediate setting” helps a reader choose. “A flexible, accessible component” does not.
Compare alternatives only when a plausible caller could confuse them. Explain accessible naming, error association or focus composition where the caller must make the choice. Keep exhaustive props in the API reference. Omit this section when there is no useful additional decision.
Structures
Show the actual public anatomy and parent/child relationship. Explain which parts are required, which are optional and what content the caller supplies. A leaf can use one sentence. A compound component needs its useful nesting, including portal/context distinctions when they matter.
Structures is not a repository file tree or a flat export list. Do not invent a Root part or require optional wrappers merely to make pages look uniform.
Examples
Admit an example when it teaches a new caller decision, state or composition. Group ordinary values such as sizes into one comparison; give distinct behavior its own example. Show combinations only when they expose a concrete risk. A different business title does not make a new variant.
Use behavior-based headings such as “Multiple selection” or “With a description”. Keep realistic content inside the demo. A full ecommerce workflow belongs in a block or template. Preview source must reproduce the rendered configuration and include necessary state, data and example CSS.
API reference
Verify every stated value and default against source. Explain callback payloads and who owns the resulting state. Distinguish controlled values from initial defaults, approval from execution and pending work from success. Describe native attributes, refs and render composition only where the current owner supports them.
Per-component checklist
| Check | Required result |
|---|---|
| Summary | One action-led sentence describing the task; canonical display name |
| Guidance | A useful choice or composition decision; omit generic praise |
| Structures | Real public nesting, required/optional parts and caller content |
| Examples | Meaningful independent configurations/states, with working previews; justify grouping or omission |
| API | Current props, defaults, callback payloads and state ownership |
| Writing | Consistent terms, necessary detail and no repetition |
The author and reviewer own these six judgments. Resolve unclear guidance, incorrect anatomy, redundant examples and unsupported API claims before accepting a page. npm run docs:check protects that work by checking names, summaries, links, executable snippets and review freshness. Changes to the page, reviewed owner/demos or writing rules invalidate the recorded review.
Library guides instead teach setup, data, state/operations and API contracts. Link the component page for styling.
Review
Check meaning and source accuracy first; remove repetition second. Compile changed MDX and executable snippets, resolve links and confirm install identities. Review the changed live result when rendering or behavior changes. A heading check does not establish content quality, and representative screenshots do not certify every component.
The repository skill at .agents/skills/component-documentation/SKILL.md contains section templates and editing examples; the writing skill download includes them. The approach draws on Google Technical Writing and Diátaxis; the section order is Ghost's project convention.