# Write Docs

> Write accurate, product-grounded documentation pages for ClassroomIO. Use when adding content to stub pages, expanding thin docs, or creating new guide pages under apps/docs/content/docs/.

- Skill: `classroomio/write-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add classroomio/write-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/classroomio/write-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: classroomio (https://skillmd.com/u/classroomio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/classroomio/write-docs

---


You are writing documentation for ClassroomIO — an LMS platform that lets organizations create and run training academies. Documentation lives in `apps/docs/content/docs/` and is rendered by Blume.

## Research before writing

Every page must reflect how the feature actually works in the product. Before writing, read the relevant source:

- **UI components / pages**: `apps/dashboard/src/lib/features/{domain}/pages/`
- **Settings pages**: `apps/dashboard/src/lib/features/settings/pages/`
- **API routes**: `apps/api/src/routes/{domain}/` and `apps/api/src/services/{domain}/`
- **DB schema**: `packages/db/src/schema.ts` — column names and types reveal the data model
- **Translations**: `apps/dashboard/src/lib/utils/translations/en.json` — use the exact UI label text from here, not guesses

Never describe behavior you haven't verified in the source code or UI.

## Terminology (use these terms everywhere)

| Term | Meaning |
|---|---|
| **academy** | The public-facing org site (`<siteName>.myclassroomio.com` or custom domain) |
| **LMS** | The authenticated student learning area (Home, My Learning, Explore, Programs) |
| **organization** | The admin workspace holding courses, people, settings, branding |
| **student** | A user enrolled in courses — never "learner" |
| **Open Academy** | The button/link that opens the public academy |
| **Academy subdomain** | The org's site name / slug field in settings |
| **academy landing page** | The public homepage for the org (not "org landing page") |
| **course landing page** | The per-course public page |

## Settings navigation paths

Settings is opened from the **account menu** in the sidebar footer, not from the org nav. Use these exact paths:

- `Settings → Profile` — personal profile settings
- `Settings → Notifications` — personal email notification preferences
- `Settings → Branding` — org name, logo, and brand color
- `Settings → Domains` — academy subdomain, custom domain, and favicon
- `Settings → Teams` — invite and manage admins and tutors
- `Settings → Customize LMS` — LMS feature toggles
- `Settings → Billing` — plan and billing
- `Settings → AI Tutor` — per-org AI tutor toggle
- `Settings → AI Credits` — token usage
- `Settings → Authentication` — signup rules, SSO, token auth; tabs: General, SSO, Token Auth
- `Settings → Authentication → General` — signup toggle, Internal Enrollment Only
- `Settings → Authentication → SSO` — enterprise SSO connections
- `Settings → Authentication → Token Auth` — Token Auth signing secret
- `Distribute → Landing Page` — academy landing page editor (org sidebar, not Settings)

Do not write `Settings → Organization` or `Settings → Landing Page`. Those paths are gone.

## MDX format conventions

Pages are rendered by Blume. Its components are global — **do not import anything**.

**Callouts** are directives, not components. Types: `note`, `info`, `tip`, `success`, `warning`, `danger`.

```mdx
:::warning[Paid plan required]
Certificate features require a paid plan.
:::
```

**Numbered `###` headings** for sequential procedures. Do not use a `<Steps>`/`<Step>` component: the
CMS reads the raw markdown, where those tags render as literal text. The heading also generates the
linkable anchor.

```mdx
### 1. Enable downloadable certificates

Turn on **Allow students download certificate**.

### 2. Set the completion threshold

Choose the percentage a student must reach.
```

A short summary of a procedure the page then covers in full can be a plain numbered list instead.

Also available without imports: `<Tabs>`/`<Tab>`, `<Card>`, `<Accordion>`, `<YouTube id="..." />`,
`<CodeGroup>`, `<Frame>`. Code fences take a title: ` ```zsh title="Terminal" `. Mermaid fences render
as diagrams.

**Links and images follow different rules** — this trips people up:

- **Links**: root-relative, no `/docs` prefix — `[Enrollment](/course-enrollment)`. Blume adds the
  base at build time.
- **Images**: must include the `/docs` prefix — `![Alt](/docs/certificates-rules.webp)`. Blume does
  not rebase images, so an unprefixed path 404s. Files live in `apps/docs/public/`.

Run `pnpm --filter @cio/docs validate` to check links and anchors.

**Frontmatter** (required on every page):
```mdx
---
title: Page Title
description: One sentence — shown in search results and link previews.
---
```

New pages must also be added to the sidebar in `apps/docs/blume.config.ts` (`navigation.sidebar`) —
a page that isn't listed there will not appear in the nav.

## Writing style

- Address the reader as "you" (the admin/instructor).
- Short, direct sentences. No filler. No "In this guide, we will…" preambles.
- Use **bold** for UI element names exactly as they appear in the product (match translations).
- Use `code` for paths, values, slugs, and field names.
- Tables for comparisons and reference lists.
- Numbered `###` headings for sequential procedures (never a `<Steps>` component).
- End every substantive page with a `## Related guides` section linking to connected pages.
- Remove the "Work in Progress" callout when replacing it with real content.

## Page structure patterns

**Reference page** (what a feature is):
1. One-paragraph description of the feature
2. Key concepts or table
3. How it fits with related features
4. Related guides

**How-to guide** (how to do something):
1. One-sentence context (what and why)
2. Prerequisites if any
3. The procedure, as numbered `###` headings
4. Common scenarios or edge cases (Callout blocks)
5. Related guides

**Overview/index page** (org, course, programs):
1. Short description
2. Table: area | where | guide
3. Related guides

## Things to avoid

- Don't describe UI that doesn't exist yet
- Don't say "workspace" — use "organization"
- Don't use "learner" — use "student"
- Don't say "org site" — say "your academy"
- Don't hardcode customer site names — use `<siteName>.myclassroomio.com` as the placeholder
- Don't add the "Work in Progress" callout to pages you've completed