From 4e24e3cb632ef2276b4b0b60a33cfef64ac72ba0 Mon Sep 17 00:00:00 2001 From: Rotimi Best Date: Wed, 10 Jun 2026 09:32:45 +0100 Subject: [PATCH] docs: add content to stubbed pages --- apps/docs/content/docs/audience.mdx | 49 +++++++- apps/docs/content/docs/community.mdx | 28 ++++- .../docs/how-to-guides/certificates.mdx | 60 +++++++++- .../docs/how-to-guides/grade-exercise.mdx | 66 ++++++++++- .../docs/how-to-guides/invite-team-member.mdx | 70 +++++++++++- .../docs/how-to-guides/take-attendance.mdx | 28 ++++- skills/write-docs/SKILL.md | 106 ++++++++++++++++++ 7 files changed, 389 insertions(+), 18 deletions(-) create mode 100644 skills/write-docs/SKILL.md diff --git a/apps/docs/content/docs/audience.mdx b/apps/docs/content/docs/audience.mdx index 3b91b9ca..fcf2d459 100644 --- a/apps/docs/content/docs/audience.mdx +++ b/apps/docs/content/docs/audience.mdx @@ -1,10 +1,53 @@ --- title: Audience -description: Information about ClassroomIO's target audience. +description: Manage all students in your organization — view status, assign to courses, and handle invites from one place. --- import { Callout } from 'fumadocs-ui/components/callout'; - - This page is a work in progress. Help us expand it by contributing! +**Audience** is your org-wide student directory. It shows every person who belongs to your organization — whether they signed up themselves, accepted a course invite, or were added directly. From here you can search, sort, bulk-assign to courses, and manage pending invites. + +## What Audience shows + +Audience is separate from course-level **People**. Course People shows who is enrolled in a specific course. Audience shows everyone in your organization regardless of which courses they have joined. + +| Column | What it means | +| --- | --- | +| **Name** | Student's display name | +| **Email** | Account email address | +| **Status** | Current membership state (see below) | +| **Date Joined** | When the student joined the organization | + +### Status values + +| Status | Meaning | +| --- | --- | +| **Active** | Student has a verified account and is a member of your org | +| **Pending** | Invite was sent but the student has not yet accepted it | +| **Expired** | The invite link passed its expiry before the student accepted | +| **Revoked** | The invite was manually revoked by an admin | + +## Assign students to courses + +Select one or more students using the checkboxes, then click **Assign to Courses**. You can pick multiple courses at once. This enrolls the selected students immediately — no action needed from them. + +## Manage pending invites + +For students with **Pending** status, you can: + +- **Resend invite** — sends a fresh invite email to that address +- **Revoke invite** — cancels the invite so the link no longer works + +## Import and export + +Use **Import Users** to bulk-add students from a CSV file. Use **Export** to download the current audience list. + + + Your plan sets a maximum audience size. When you reach the limit, a banner appears and you cannot invite more students until you upgrade or remove existing members. + +## Related guides + +- [How Course Enrollment Works](/docs/how-to-guides/course-enrollment) — how students join courses +- [How to Invite Students](/docs/how-to-guides/invite-students) — send course-specific invites +- [Roles and Permissions](/docs/how-to-guides/roles-and-permissions) — difference between students and team members diff --git a/apps/docs/content/docs/community.mdx b/apps/docs/content/docs/community.mdx index 01f1ffce..231fd2a1 100644 --- a/apps/docs/content/docs/community.mdx +++ b/apps/docs/content/docs/community.mdx @@ -1,10 +1,32 @@ --- title: Community -description: Join the ClassroomIO community. +description: An org-wide Q&A forum where students and instructors can ask questions, share answers, and discuss topics across all courses. --- import { Callout } from 'fumadocs-ui/components/callout'; - - This page is a work in progress. Help us expand it by contributing! +**Community** is an org-wide Q&A forum. Anyone in your organization can post a question, answer others, or leave comments. Questions can be tied to a specific course or posted for the whole organization to see. + +## How it works + +- Anyone in the org (students, tutors, and admins) can ask a question and participate in discussions. +- When asking, you can optionally link the question to a course so students in that course can find it easily. +- Other members can answer and comment on each thread. +- You can search for questions using **Find Question**. + +## Asking a question + +From the **Community** section in the sidebar, click **Ask Community**. Fill in a title and the question body, optionally select a course, and click **Publish**. The question is immediately visible to your org. + +## Moderating questions + +Admins can delete any question or comment. Authors can edit or delete their own posts. + + + Community is org-wide and searchable across all courses. The **Newsfeed** tab inside each course is a course-scoped activity feed for announcements and updates — it is not a Q&A forum. + +## Related guides + +- [Course](/docs/course) — course-level features including Newsfeed +- [Roles and Permissions](/docs/how-to-guides/roles-and-permissions) — who can post and moderate diff --git a/apps/docs/content/docs/how-to-guides/certificates.mdx b/apps/docs/content/docs/how-to-guides/certificates.mdx index 2d39ed36..b63e0191 100644 --- a/apps/docs/content/docs/how-to-guides/certificates.mdx +++ b/apps/docs/content/docs/how-to-guides/certificates.mdx @@ -1,10 +1,64 @@ --- title: How to Create Certificates -description: Learn how to create certificates for your course. +description: Configure certificate rules for a course, set completion requirements, and let students download their certificates. --- import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; - - This page is a work in progress. Help us expand it by contributing! +Certificates recognize students for completing a course. You configure the rules on a per-course basis — what score is required, whether a final exercise must be passed, and when certificates expire. Students can then download their certificate from the **Certificates** tab in the LMS. + +## Configure certificate rules + +Open your course in the admin dashboard and go to the **Certificates** tab. + + + +### Enable downloadable certificates + +Turn on **Allow students to download their certificate**. When this is off, no certificate is generated even if students meet the requirements. + + + +### Set a completion threshold + +Enter a percentage in **Minimum score to receive certificate**. A student must reach this overall course score to qualify. Defaults to 100%. + + + +### Require a final exercise (optional) + +Select an exercise from **Final exercise**. When set, the student must pass that specific exercise in addition to meeting the overall threshold. Set **Minimum exercise score** to the minimum passing score for that exercise. + + + +### Set a deadline (optional) + +Enter a date and time in **Certificate deadline**. Students who complete the course after this date do not receive a certificate. + + + +### Add a custom email message (optional) + +Enter text in the email message field. This message is included in the notification email sent to students when they earn their certificate. + + + +## What students see + +Once a student meets all the configured requirements, their certificate appears in the **Certificates** tab when they open the course in the LMS. They can view and download it from there. + + + Admins can also issue a certificate to a specific student manually using the **Issue Certificate** button at the top of the Certificates tab, regardless of whether the student met the automatic requirements. + + + Certificate features require a paid plan. The controls are visible on free plans but disabled. + + +## Related guides + +- [Creating Your First Course](/docs/how-to-guides/create-first-course) — course setup overview +- [How to Create an Exercise](/docs/how-to-guides/create-exercise) — create the exercise you reference as a final exercise +- [How to Grade an Exercise](/docs/how-to-guides/grade-exercise) — grade submissions before certificates are issued +- [Student Dashboard](/docs/student-dashboard) — where students access their certificates diff --git a/apps/docs/content/docs/how-to-guides/grade-exercise.mdx b/apps/docs/content/docs/how-to-guides/grade-exercise.mdx index 51bcca43..e7633c42 100644 --- a/apps/docs/content/docs/how-to-guides/grade-exercise.mdx +++ b/apps/docs/content/docs/how-to-guides/grade-exercise.mdx @@ -1,11 +1,71 @@ --- title: How to Grade an Exercise -description: Learn how to grade exercises submitted by students. +description: Review student submissions, move them through the grading workflow, score answers, and leave feedback. --- import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +When students submit exercises, their work appears in the **Submissions** tab of the course dashboard. Exercises move through a three-stage workflow: **Submitted → In Progress → Graded**. - - This page is a work in progress. Help us expand it by contributing! +## Grading workflow + +| Stage | Meaning | +| --- | --- | +| **Submitted** | Student has submitted; not yet reviewed | +| **In Progress** | You have opened the submission for review | +| **Graded** | Review is complete and the grade is recorded | + +Submissions are displayed as cards on a board. Drag a card between columns or open it to change its status manually. + + + Exercises that use only objective question types (multiple choice, etc.) are auto-graded when submitted. They move directly to **Graded** without manual review. Exercises with open-ended or video questions require manual review and are flagged **Manual grading required**. + +## Grade a submission + + + +### Open the Submissions tab + +From the course dashboard, click **Submissions** in the top navigation. + + + +### Open a submission + +Click any card in the **Submitted** column. The grading modal opens showing the student's answers, a score breakdown, and a comment field. + + + +### Review and score + +Each question shows the student's answer alongside the expected answer or rubric. Scores are calculated automatically where possible. Adjust individual question scores if needed. + + + +### Leave a comment (optional) + +Type feedback in **Add comment**. The student can see this after grading is complete. + + + +### Submit the grade + +Click **Submit Grades**. The card moves to **Graded** and the student's score is recorded. + + + +## Grade with AI + +Click **Grade with AI** inside the grading modal to get an AI-suggested score and rationale for open-ended answers. Review the suggestion and click **Accept** to apply it or **Reject** to discard it and grade manually. + + + AI grading is a suggestion. Always review the reasoning before accepting, especially for nuanced or context-dependent answers. + + +## Related guides + +- [How to Create an Exercise](/docs/how-to-guides/create-exercise) — create and configure exercises +- [How to Create Certificates](/docs/how-to-guides/certificates) — certificates that depend on exercise scores +- [Course](/docs/course) — course overview including the Submissions tab diff --git a/apps/docs/content/docs/how-to-guides/invite-team-member.mdx b/apps/docs/content/docs/how-to-guides/invite-team-member.mdx index a8f44cf4..9d861029 100644 --- a/apps/docs/content/docs/how-to-guides/invite-team-member.mdx +++ b/apps/docs/content/docs/how-to-guides/invite-team-member.mdx @@ -1,11 +1,75 @@ --- title: Inviting a Team Member -description: Learn how to invite team members to your organization. +description: Add admins and tutors to your organization by email invite or a reusable invite link. --- import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +Team members are people who help you run your organization — **Admins** have full access, **Tutors** can manage the courses they are assigned to. Both are different from students, who use the LMS and cannot access the admin dashboard. - - This page is a work in progress. Help us expand it by contributing! +To invite a team member, go to **Settings → Organization**, then click **Manage Team**. + +## Invite by email + + + +### Enter email addresses + +Type one or more email addresses into the invite field. Separate multiple addresses with commas. + + + +### Select a role + +Choose **Admin** or **Tutor** from the role dropdown. + + + +### Send the invite + +Click **Send invite**. Each recipient receives an email with a link to join your organization at the selected role. + + + +Invited members appear in the team list with an **Invite Sent** badge until they accept. You can remove a pending or accepted member at any time using the **Remove** button next to their name. + +## Invite by link + +A link invite lets you share one URL that anyone can use to join your org at a specific role — useful for onboarding multiple people at once without entering individual email addresses. + + + +### Select a role for the link + +Choose **Admin** or **Tutor**. + + + +### Generate the link + +Click **Generate**. A shareable URL appears. + + + +### Copy and share + +Click **Copy** and share the link however you prefer. Anyone who opens it and signs in (or signs up) joins your org at the selected role. + + + +### Disable the link when done + +Toggle the link off to stop accepting new members through it. You can re-enable it later or generate a new link. + + + + + Email invites and link invites for team members require a paid plan. + +## Related guides + +- [Roles and Permissions](/docs/how-to-guides/roles-and-permissions) — what admins and tutors can do +- [How to Invite Students](/docs/how-to-guides/invite-students) — invite students to a specific course (separate from team invites) +- [Organization](/docs/organization) — org settings overview diff --git a/apps/docs/content/docs/how-to-guides/take-attendance.mdx b/apps/docs/content/docs/how-to-guides/take-attendance.mdx index 2d344589..11d5b29b 100644 --- a/apps/docs/content/docs/how-to-guides/take-attendance.mdx +++ b/apps/docs/content/docs/how-to-guides/take-attendance.mdx @@ -1,11 +1,33 @@ --- title: How to Take Attendance -description: Learn how to take attendance for your classes. +description: Record lesson attendance for each student in a course using the Attendance tab. --- import { Callout } from 'fumadocs-ui/components/callout'; +The **Attendance** tab in a course lets you track which students attended each lesson. Only students who are enrolled in the course appear in the attendance grid — enroll them first via **People** if they are missing. It displays a grid with students as rows and lessons as columns. A checked box means the student was present; unchecked means absent. - - This page is a work in progress. Help us expand it by contributing! +## Mark attendance + +From the course dashboard, open the **Attendance** tab. + +- Check the box at the intersection of a student and a lesson to mark them **Present**. +- Uncheck the box to mark them **Absent**. + +Changes save immediately — there is no separate save button. + +Use the search bar to filter students by name if the course has a large group. + + + Students can view their own attendance record in the Attendance tab when they open the course in the LMS, but they cannot edit it. + +## Pagination + +The table shows 10 students per page. Use the page controls at the bottom to move between pages. + +## Related guides + +- [Creating Your First Course](/docs/how-to-guides/create-first-course) — adding lessons to a course +- [How Course Enrollment Works](/docs/how-to-guides/course-enrollment) — how students join a course +- [Course](/docs/course) — course overview and available tabs diff --git a/skills/write-docs/SKILL.md b/skills/write-docs/SKILL.md new file mode 100644 index 00000000..1fdf7330 --- /dev/null +++ b/skills/write-docs/SKILL.md @@ -0,0 +1,106 @@ +--- +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) + +| Term | Meaning | +|---|---| +| **academy** | The public-facing org site (`.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 + +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: + +```mdx +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): +```mdx +--- +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 `.myclassroomio.com` as the placeholder +- Don't add the "Work in Progress" callout to pages you've completed