diff --git a/DOCS_GUIDELINES.md b/DOCS_GUIDELINES.md new file mode 100644 index 000000000..89a915ba9 --- /dev/null +++ b/DOCS_GUIDELINES.md @@ -0,0 +1,148 @@ +# Documentation Guidelines + +Standards for writing and maintaining Hyperframes documentation. Based on patterns from Remotion, Stripe, Tailwind CSS, and Astro. + +## Core Principles + +1. **One-sentence intro rule** — Every page opens with a single sentence telling the reader what this page helps them do or understand. No preamble, no history. + +2. **Outcome before implementation** — Show what the code produces (rendered result, terminal output, file structure) before showing the code itself. + +3. **Show, don't tell** — Use concrete examples with realistic values. Never use `foo`/`bar`/`baz`. Prefer a working HTML snippet over a description of what to write. + +4. **Two content modes** — Guides build narratives with progressive complexity. References enable scanning with standardized structure. Never mix them. + +5. **No dead ends** — Every page links forward (next steps), backward (prerequisites), and sideways (related concepts). Readers should never reach a page with nowhere to go. + +## Page Structure + +### Guides (concepts/, guides/) + +``` +Title +├── One-sentence purpose statement +├── What this looks like (output, demo, or visual) +├── Minimal working example +├── Deeper explanation with progressive complexity +├── Common patterns / best practices +├── Warnings and pitfalls (sparingly) +└── Next steps (cards or links to related pages) +``` + +### Reference pages (reference/) + +``` +Title +├── One-sentence definition +├── Complete attribute/API table +├── Detailed section per item (type, default, description, example) +├── Rules and constraints +└── Related pages +``` + +### Package pages (packages/) + +``` +Title +├── One-line description + install command +├── When to use this package (and when NOT to) +├── Key features list +├── Minimal usage example with expected output +├── Configuration reference +└── Related packages +``` + +## Writing Style + +- **Second person, active voice, imperative mood**: "Use X to do Y." Not "The developer should consider using X." +- **Present tense**: "The runtime manages media playback." Not "The runtime will manage..." +- **Be direct**: "This breaks rendering." Not "This may potentially cause issues with the rendering pipeline." +- **Prerequisites at point of need**: State requirements where they matter, not in a wall at the top. +- **Conversational but precise**: Friendly tone, exact technical details. + +## Code Examples + +### Always annotate code blocks + +```mdx +```html index.html +
+```​ +``` + +The filename after the language tag tells readers where the code goes. + +### Use numbered comments for multi-step code + +```javascript +// 1. Create a paused timeline +const tl = gsap.timeline({ paused: true }); + +// 2. Add animations +tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0); + +// 3. Register the timeline +window.__timelines["my-video"] = tl; +``` + +### Show expected output + +After CLI commands, show what the user should see: + +```bash +npx hyperframes dev +# ✓ Server running at http://localhost:3000 +# ✓ Watching for changes... +``` + +### Use CodeGroup for multi-platform commands + +```mdx + +```bash macOS +brew install ffmpeg +```​ +```bash Ubuntu +sudo apt install ffmpeg +```​ + +``` + +## Mintlify Components — When to Use + +| Component | Use When | +|-----------|----------| +| `` | Sequential setup or tutorial instructions | +| `` | Same action across platforms/languages | +| `` | Alternative approaches with equal weight | +| `` / `` | Navigation to related pages, next steps | +| `` | FAQ or optional detail that would bloat the page | +| `` | Non-obvious behavior the reader should know | +| `` | Something that will break if ignored | +| `` | Helpful shortcut or best practice | +| `` | Context that aids understanding | +| `` | File/directory structure | +| `` | Screenshots or diagrams with captions | + +### Callout budget: max 2-3 per page + +More than 3 callouts creates alert fatigue and readers skip them all. Reserve `` for things that genuinely break. Use inline prose for tips. + +## Cross-Linking + +- **Link at the point of curiosity**: When you mention a concept that has its own page, link it immediately. Don't hoard links. +- **"See also" at page bottom**: Only for genuinely related content that doesn't fit inline. +- **Next steps cards**: End guide pages with `` links to logical next pages. + +## File Conventions + +- All doc pages are `.mdx` (not `.md`) +- Use kebab-case for filenames: `frame-adapters.mdx`, not `frameAdapters.mdx` +- Frontmatter requires `title` and `description` +- Description should be under 160 characters (used for SEO/social) + +## Maintenance + +- Docs live in the repo at `/docs` and deploy automatically on merge to `main` +- PRs that change user-facing behavior should update relevant doc pages +- Run `mint validate` and `mint broken-links` before pushing doc changes diff --git a/docs/concepts/compositions.mdx b/docs/concepts/compositions.mdx index 5b1ce3def..ea9872163 100644 --- a/docs/concepts/compositions.mdx +++ b/docs/concepts/compositions.mdx @@ -3,105 +3,159 @@ title: Compositions description: "The fundamental building block of a Hyperframes video." --- -A composition is an HTML document that defines a video timeline. Every clip — video, image, audio — must live inside a composition. +A composition is an HTML document that defines a video timeline. Every clip -- video, image, audio -- lives inside a composition. ## Structure Every composition needs a root element with `data-composition-id`: -```html +```html index.html
``` -The `index.html` file is the top-level composition. It can contain nested compositions within it. Any composition can be imported into another — there is no special "root" type. +The `index.html` file is the top-level composition. It can contain nested compositions within it. Any composition can be imported into another -- there is no special "root" type. ## Clip Types -A clip is any discrete block on the timeline, represented as an HTML element with data attributes: +A clip is any discrete block on the timeline, represented as an HTML element with [data attributes](/concepts/data-attributes): -- `