docs

Docs

Write documentation for Video.js 10.

Reference Material

Load these files based on task:

Principles

Fast

• Optimize for static generation
• Fast search (Pagefind or Algolia)

Readable

• Be concise — every token must earn its place
• Avoid jargon and idioms
• Optimize for skimming (bold, lists, headings)
• Simple first-time experience, reveal complexity gradually
• Many code examples you can copy/paste

Helpful

• Document workarounds even for product gaps
• Include migration guides for breaking changes
• Easy to leave feedback

AI-Native

• Prefer code over "click here"
• Prefer prompts over lengthy tutorials
• Serve llms.txt as docs directory
• Support .md URL suffix for markdown view

Agent-Ready

• Pages easy to copy as markdown
• Ship docs in package (JSDoc, README)
• Include AGENTS.md with library
• Self-contained examples with all imports

Polished

• Every heading linkable with stable anchors
• Cross-link related guides, APIs, examples
• Good metadata for search

Accessible

• Alt tags on images
• Respect prefers-reduced-motion

Tone & Style

Direct. Confident. Friendly but not chatty.

// ❌ Wordy
In order to create a new player instance, you'll need to call the
createPlayer function and pass in a configuration object.

// ✅ Direct
Create a player:

const player = createPlayer({ src: 'video.mp4' });

Rules:

• Active voice, second person ("you")
• Short sentences
• No filler ("In order to", "basically", "simply")
• No hedging ("might", "could", "perhaps")
• Code does the heavy lifting

Do/Don't Pattern

Show why something is better:

### Requesting State Changes

// ❌ Don't — mutate directly
video.volume = 0.5; // No coordination, no error handling

// ✅ Do — use requests
await player.request.setVolume(0.5); // Queued, cancellable, tracked

Familiar Terms

Explain using ecosystem patterns:

// ✅ Good
Requests work like HTTP — you ask, the target responds asynchronously.

// ✅ Good
State flows down like React context. Events bubble up like DOM events.

Cross-Linking

• Reference related pages liberally
• Repetition across pages is okay — users land anywhere
• Add "See also" sections

Documentation Types

Prefer handbooks. Most documentation should be handbook pages — one concept, quickly scannable. Use guides only for true tutorials that build something from scratch.

README

Light (has site docs): Description, install, one example, link.

Comprehensive (no site docs): Full API, progressive examples.

Handbook (Preferred)

Bite-sized reference pages. One concept, quickly scannable. Users skim while building.

Use for: Concepts, patterns, configuration, troubleshooting, "how do I X?"

Reference: Base UI handbook (styling, composition, TypeScript, forms).

## Styling

Style components using data attributes and CSS variables.

.slider[data-dragging] {
cursor: grabbing;
}

### Data Attributes

Components expose state via `data-*` attributes...

### CSS Variables

Dynamic values for sizing and transforms...

**See also:** [Tailwind Integration](/handbook/tailwind)

Guides (Rare)

Narrative tutorials. Step-by-step, teaches "why", builds toward something complete.

Use sparingly for: Getting Started, Building X from Scratch. Most "guide-like" content should be a handbook page instead.

Reference: Tailwind Core Concepts.

## Building a Custom Player

This guide walks through building a player from scratch.

### Prerequisites

...

### Step 1: Set up the store

...

### Step 2: Create the UI

...

### What's next?

...

Handbook vs Guides:

API Reference

Structure: Example → Anatomy → Options → Returns → Data Attributes → See Also

See templates/api-reference.md for full template.

Component Pages

Structure: Example → Features → Installation → Anatomy → API Reference → Examples → Accessibility

See templates/component-page.md for full template.

Video.js 10 Architecture

When documenting, understand the package hierarchy:

Dependency flow: utils → store → core → html / react / react-native

Document @videojs/store as state primitives (features, requests, guards). Document @videojs/html as Web Components with controllers and mixins. Document framework adapters with framework-native idioms.

Output Locations

packages/{name}/README.md          — readme (primary docs until site launches)
packages/{name}/CLAUDE.md          — agent instructions
site/src/content/docs/api/         — API reference
site/src/content/docs/handbook/    — handbook
site/src/content/docs/guides/      — guides
site/src/content/docs/components/  — components
site/public/llms.txt               — AI docs index

Note: Site structure (site/src/content/docs/) not yet created. Package READMEs are the primary documentation until the site launches.

Process

1. Determine doc type (handbook preferred; guide only for true tutorials)
2. Load relevant reference/pattern/template files
3. Check existing style in codebase
4. Write concise draft with examples
5. Add do/don't where helpful
6. Add cross-links to related pages
7. Verify examples pass linting and types
8. Cut anything unnecessary

Review

For reviewing existing documentation against these standards, load review/workflow.md.

Related Skills