|
| 1 | +# Documentation Guidelines |
| 2 | + |
| 3 | +Standards for writing and maintaining Hyperframes documentation. Based on patterns from Remotion, Stripe, Tailwind CSS, and Astro. |
| 4 | + |
| 5 | +## Core Principles |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +2. **Outcome before implementation** — Show what the code produces (rendered result, terminal output, file structure) before showing the code itself. |
| 10 | + |
| 11 | +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. |
| 12 | + |
| 13 | +4. **Two content modes** — Guides build narratives with progressive complexity. References enable scanning with standardized structure. Never mix them. |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +## Page Structure |
| 18 | + |
| 19 | +### Guides (concepts/, guides/) |
| 20 | + |
| 21 | +``` |
| 22 | +Title |
| 23 | +├── One-sentence purpose statement |
| 24 | +├── What this looks like (output, demo, or visual) |
| 25 | +├── Minimal working example |
| 26 | +├── Deeper explanation with progressive complexity |
| 27 | +├── Common patterns / best practices |
| 28 | +├── Warnings and pitfalls (sparingly) |
| 29 | +└── Next steps (cards or links to related pages) |
| 30 | +``` |
| 31 | + |
| 32 | +### Reference pages (reference/) |
| 33 | + |
| 34 | +``` |
| 35 | +Title |
| 36 | +├── One-sentence definition |
| 37 | +├── Complete attribute/API table |
| 38 | +├── Detailed section per item (type, default, description, example) |
| 39 | +├── Rules and constraints |
| 40 | +└── Related pages |
| 41 | +``` |
| 42 | + |
| 43 | +### Package pages (packages/) |
| 44 | + |
| 45 | +``` |
| 46 | +Title |
| 47 | +├── One-line description + install command |
| 48 | +├── When to use this package (and when NOT to) |
| 49 | +├── Key features list |
| 50 | +├── Minimal usage example with expected output |
| 51 | +├── Configuration reference |
| 52 | +└── Related packages |
| 53 | +``` |
| 54 | + |
| 55 | +## Writing Style |
| 56 | + |
| 57 | +- **Second person, active voice, imperative mood**: "Use X to do Y." Not "The developer should consider using X." |
| 58 | +- **Present tense**: "The runtime manages media playback." Not "The runtime will manage..." |
| 59 | +- **Be direct**: "This breaks rendering." Not "This may potentially cause issues with the rendering pipeline." |
| 60 | +- **Prerequisites at point of need**: State requirements where they matter, not in a wall at the top. |
| 61 | +- **Conversational but precise**: Friendly tone, exact technical details. |
| 62 | + |
| 63 | +## Code Examples |
| 64 | + |
| 65 | +### Always annotate code blocks |
| 66 | + |
| 67 | +```mdx |
| 68 | +```html index.html |
| 69 | +<div data-composition-id="root" ...> |
| 70 | +``` |
| 71 | +``` |
| 72 | + |
| 73 | +The filename after the language tag tells readers where the code goes. |
| 74 | + |
| 75 | +### Use numbered comments for multi-step code |
| 76 | + |
| 77 | +```javascript |
| 78 | +// 1. Create a paused timeline |
| 79 | +const tl = gsap.timeline({ paused: true }); |
| 80 | + |
| 81 | +// 2. Add animations |
| 82 | +tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0); |
| 83 | + |
| 84 | +// 3. Register the timeline |
| 85 | +window.__timelines["my-video"] = tl; |
| 86 | +``` |
| 87 | + |
| 88 | +### Show expected output |
| 89 | + |
| 90 | +After CLI commands, show what the user should see: |
| 91 | + |
| 92 | +```bash |
| 93 | +npx hyperframes dev |
| 94 | +# ✓ Server running at http://localhost:3000 |
| 95 | +# ✓ Watching for changes... |
| 96 | +``` |
| 97 | + |
| 98 | +### Use CodeGroup for multi-platform commands |
| 99 | + |
| 100 | +```mdx |
| 101 | +<CodeGroup> |
| 102 | +```bash macOS |
| 103 | +brew install ffmpeg |
| 104 | +``` |
| 105 | +```bash Ubuntu |
| 106 | +sudo apt install ffmpeg |
| 107 | +``` |
| 108 | +</CodeGroup> |
| 109 | +``` |
| 110 | + |
| 111 | +## Mintlify Components — When to Use |
| 112 | + |
| 113 | +| Component | Use When | |
| 114 | +|-----------|----------| |
| 115 | +| `<Steps>` | Sequential setup or tutorial instructions | |
| 116 | +| `<CodeGroup>` | Same action across platforms/languages | |
| 117 | +| `<Tabs>` | Alternative approaches with equal weight | |
| 118 | +| `<Card>` / `<Columns>` | Navigation to related pages, next steps | |
| 119 | +| `<Accordion>` | FAQ or optional detail that would bloat the page | |
| 120 | +| `<Note>` | Non-obvious behavior the reader should know | |
| 121 | +| `<Warning>` | Something that will break if ignored | |
| 122 | +| `<Tip>` | Helpful shortcut or best practice | |
| 123 | +| `<Info>` | Context that aids understanding | |
| 124 | +| `<Tree>` | File/directory structure | |
| 125 | +| `<Frame>` | Screenshots or diagrams with captions | |
| 126 | + |
| 127 | +### Callout budget: max 2-3 per page |
| 128 | + |
| 129 | +More than 3 callouts creates alert fatigue and readers skip them all. Reserve `<Warning>` for things that genuinely break. Use inline prose for tips. |
| 130 | + |
| 131 | +## Cross-Linking |
| 132 | + |
| 133 | +- **Link at the point of curiosity**: When you mention a concept that has its own page, link it immediately. Don't hoard links. |
| 134 | +- **"See also" at page bottom**: Only for genuinely related content that doesn't fit inline. |
| 135 | +- **Next steps cards**: End guide pages with `<Card>` links to logical next pages. |
| 136 | + |
| 137 | +## File Conventions |
| 138 | + |
| 139 | +- All doc pages are `.mdx` (not `.md`) |
| 140 | +- Use kebab-case for filenames: `frame-adapters.mdx`, not `frameAdapters.mdx` |
| 141 | +- Frontmatter requires `title` and `description` |
| 142 | +- Description should be under 160 characters (used for SEO/social) |
| 143 | + |
| 144 | +## Maintenance |
| 145 | + |
| 146 | +- Docs live in the repo at `/docs` and deploy automatically on merge to `main` |
| 147 | +- PRs that change user-facing behavior should update relevant doc pages |
| 148 | +- Run `mint validate` and `mint broken-links` before pushing doc changes |
0 commit comments