write-docs

name: write-docs description: 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/.

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 Fumadocs.

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)

Settings navigation paths

These are the exact sidebar paths in the admin dashboard:

• Settings → Profile — personal profile settings
• Settings → Organization — org name, logo, theme, and links to Custom Domain and Teams sub-pages
• Settings → Organization → Custom Domain — navigated to via "Edit domain" button inside Organization
• Settings → Organization → Teams — navigated to via "Manage Team" button inside Organization
• Settings → Landing Page — academy landing page editor
• Settings → Authentication — signup rules, SSO, token auth; sub-tabs: General, SSO, Token Auth
• Settings → Authentication → General — signup toggle, Internal Enrollment Only
• Settings → Billing — plan and billing
• Settings → AI Credits — token usage
• Settings → AI Tutor — per-org AI tutor toggle

MDX format conventions

All pages use Fumadocs components. Available imports:

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Callout types: info, warn, error

Frontmatter (required on every page):

---
title: Page Title
description: One sentence — shown in search results and link previews.
---

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.
• Steps component for sequential procedures (not numbered markdown lists).
• 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. Steps component with the procedure
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