docs

name: docs description: >- Write and review documentation for Video.js 10 — site pages, READMEs, and JSDoc. Use for writing concept pages, how-to guides, package READMEs, and inline API docs. Component reference pages use the api-reference skill instead. Triggers: "write docs", "create guide", "review docs", "audit documentation", "write README", "JSDoc", "inline docs".

Docs

Write documentation for Video.js 10.

Before you start

Read the relevant sources of truth before writing any documentation:

This skill adds writing guidance on top of those. When in doubt, the source files win.

Reference material

Documentation types

Site documentation (Diataxis)

The site follows the Diataxis framework:

When in doubt, write a concept page. Most new documentation should be concept pages.

Package documentation

JSDoc

CLAUDE.md (repo root) defines the hard rules — no redundant @param/@returns, no obvious comments, minimal JSDoc. This section adds a decision framework for when to write JSDoc.

Decision tree

Is the export public (used outside the package)?
├─ No → Skip JSDoc
└─ Yes → Is the name self-documenting?
         ├─ Yes (e.g., `supportsIdleCallback()`) → Skip JSDoc
         └─ No → Does it have complex generics or non-obvious behavior?
                  ├─ Yes → JSDoc with @param/@example as needed
                  └─ No → One-sentence summary

Patterns (from the codebase)

Minimal — One-sentence summary when the name is mostly clear but context helps:

// packages/utils/src/number/number.ts
/** Clamp a value between min and max (inclusive). */
export function clamp(value: number, min: number, max: number): number {

With example — Summary + @example when usage isn't obvious from the signature:

// packages/store/src/react/hooks/use-store.ts
/**
 * Access store state and actions.
 *
 * Without selector: Returns the store, does NOT subscribe to changes.
 * With selector: Returns selected state, re-renders when selected state changes (shallowEqual).
 *
 * @example
 * ```tsx
 * // Store access (no subscription) - access actions, subscribe without re-render
 * function Controls() {
 *   const { setVolume } = useStore(store);
 * }
 *
 * // Selector-based subscription - re-renders when paused changes
 * function PlayButton() {
 *   const paused = useStore(store, (s) => s.paused);
 *   return <button>{paused ? 'Play' : 'Pause'}</button>;
 * }
 * ```
 */

With params — @param/@returns for complex generics where TypeScript alone isn't enough:

// packages/store/src/core/combine.ts
/**
 * Combines multiple slices into a single slice.
 *
 * @param slices - The slices to combine.
 * @returns A new slice that represents the combination of the input slices.
 */
export function combine<Target, const Slices extends Slice<Target, any>[]>(
  ...slices: Slices
): Slice<Target, UnionSliceState<Slices>> {

Writing principles

For full guidelines, load references/writing-style.md. The essentials:

• Direct. No filler ("In order to", "basically", "simply"). No hedging ("might", "could").
• Code-first. Show the code, then explain. Not the other way around.
• Scannable. Bold, lists, headings, tables. Walls of text become tables or lists.
• Self-contained examples. Include all imports. Use realistic values, not foo/bar.
• Show output. When the result isn't obvious, add a comment showing expected output.
• Progressive. Start with the simplest version. Add complexity in later examples.
• Cross-link. Generously link related concepts and references. Repetition across pages is fine — readers land anywhere.

Do/don't contrasts

Use // ❌ Don't / // ✅ Do pairs to show why something is better. Effective for common mistakes, API misuse, and style guidance. Always explain why the wrong way is wrong.

Callout types

Use <Aside> (never :::note syntax):

MDX components

Full documentation is in site/CLAUDE.md. Quick reference:

Key gotchas:

• All <Tab*> components require client:idle — never client:visible
• No H1 — page title comes from frontmatter
• Only .mdx files, never .md

Process

1. Determine doc type — site page (concept preferred), README, or JSDoc
2. Load the relevant template or reference
3. Check existing docs for style and patterns
4. Write concise draft — code before prose
5. Add do/don't contrasts where helpful
6. Add cross-links
7. Site pages only: Add page to sidebar in site/src/docs.config.ts
8. Site pages only: Verify it renders for all framework combinations

Review

• Quick review (single agent): Load review/checklist.md
• Full review (multi-agent): Load review/workflow.md

Related skills