rootnode-academy/docs/COURSE_AUTHORING_STANDARD.md

Course Authoring Standard

Phase 6A §11 — the standard every future RootNode lesson/module must follow, so a future Claude Code session or a human instructor can author content consistently. The module at content/root/root-10-kubernetes-troubleshooting-observability/m01-health-probes/ (backing root-10-m01-health-probes-and-troubleshooting) is the reference implementation — when in doubt, read it before writing new content.

1. Target learner

State explicitly, in the module's Postgres description (not buried in prose): who this is for and what they're assumed to already know. root_ targets ages ~15-18+ through adult learners (see docs/PHASE6A_ROOT_COURSE_FOUNDATION.md §1) — write at a level that respects that range; don't write down to it.

2. Prerequisites

Declare real prerequisite course/module ids in the prerequisites column, not prose alone (see docs/COURSE_CONTENT_MODEL.md §5 for how locking derives from this). If a module assumes a concept the platform doesn't yet teach anywhere, say so explicitly in the module description rather than silently assuming it.

3. Measurable objectives

3-5 objectives per module, stored in the objectives column, each a sentence that starts with a verb describing an observable capability ("Diagnose...", "Configure...", "Explain..."), not a topic list ("Probes"). A learner (or an instructor) should be able to look at an objective and know whether it was met.

4. Estimated time

Set estimated_duration_minutes per activity and let the module/course total derive from the sum — don't hand-guess a module-level number that doesn't match its activities. Time estimates are honest guesses, not commitments; revise them once real completion-time data exists (the mechanically-mapped modules' per-scenario 15/20/30-minute estimates in 022_course_content.sql are explicitly flagged as a rough heuristic for exactly this reason).

5. Concept explanation (the lesson activity)

Explain the underlying concept BEFORE any lab is presented — this is the module's core pedagogical premise (see docs/PHASE6A_ROOT_COURSE_FOUNDATION.md's "core product principle"). Cover: why the concept/mechanism exists (the problem it solves), the mechanism itself, and common real-world mistakes. Use concrete, runnable examples (kubectl output, YAML snippets) over abstract description wherever possible.

6. Demonstration

Show the concept in action with a worked example BEFORE asking the learner to do it themselves. A demonstration activity should include what the learner would actually SEE (real-looking command output), not just a description of what would happen.

7. Guided practice (the guided_exercise activity)

Lower-stakes practice with a visible worked answer to check against (paper/scratch-file exercises are fine — see the gold module's readiness-probe exercise). The goal is committing to an answer and comparing, not passively reading a correct one first.

8. Independent practice → lab mapping

A lab activity references an EXISTING scenario_id — never invent duplicate lab content when an existing scenario already teaches the concept (check docs/ROOT_CURRICULUM_INVENTORY.md first). Write a short content_path intro (see the gold module's 05-lab-intro.md) that connects what was just taught to the incident the student is about to solve, without handing out the scenario's own hints/solution — the Lab's own progressive hints stay the only place the actual answer path lives.

Classifying near-duplicate or advanced scenarios (Phase 6B)

When two scenarios teach essentially the same concept (e.g. pod-security-context and cks-pod-security-context), don't wire both as required core labs — pick the better-fitting one as CORE and mark the other is_required = false as INDEPENDENT PRACTICE (see docs/ROOT_CURRICULUM_COVERAGE_MATRIX.md's "duplicate concepts identified" for worked examples). Likewise, a genuinely harder or more niche scenario (CKS-exam-style, a less commonly needed skill) belongs as is_required = false GUIDED/ADVANCED practice, not force-fit into the required core path just because it exists — see docs/COURSE_CONTENT_MODEL.md's optional-vs- required section for how this affects module completion.

9. Knowledge check

A handful of self-check questions with answers shown inline (not a graded exam — that's what the assessment engine is for). Use plain Markdown (*Answer:* after each question), not raw HTML <details> — react-markdown renders this repo's course content and does not have rehype-raw enabled, so raw HTML tags render as literal text, not a collapsible element.

10. Reflection

A reflection activity consolidates and connects to real-world judgment — it is not a second knowledge check. Ask "why does this matter beyond this one Lab," not "what did you just do." Include a "Real Ops takeaway": a concrete prevention/production practice a learner could apply on a real team.

11. Instructor notes

Every activity type CAN have an ## Instructor Notes section (see docs/COURSE_CONTENT_MODEL.md §3); a lesson/demonstration/guided_exercise/reflection activity SHOULD have one. At minimum include: approximate timing, one likely misconception to watch for, and (where relevant) a discussion question or optional extension activity. Keep it actionable — a bullet list an instructor can glance at mid-class, not a second essay.

12. Accessibility/readability

Plain Markdown only (headings, lists, code fences, bold/italic, tables) — no content that depends on color alone to convey meaning, no ASCII art carrying information a screen reader would lose. Write short paragraphs; prefer lists over dense prose for anything enumerable (steps, mistakes, questions).

13. Terminology rules

Match the terminology the scenario JSON and existing Platform UI already use exactly (e.g. "readiness probe," not "health check probe" — check scenarios/data/<id>.json's own description/hints for the canonical phrasing before introducing a lesson's own term for the same thing). Define a term the first time it's used in a module; don't assume a prerequisite module's terminology carried over without a one-line reminder.

14. Versioning

Bump the version integer on courses/course_modules/module_activities by hand on any semantic content edit — same convention assessment_definitions/programs already use. A version bump is informational only in Phase 6A (nothing snapshots against it the way an assessment session snapshots its definition version) — it exists so a future phase can detect "this changed since a student last saw it" without re-deriving that from updated_at alone.

15. Review/testing requirements

Before marking a module status = 'ready':

• Every activity's content_path file must exist and load (verify via platform/api/src/content.js's loadContent, or just hit the admin curriculum API and check body is non-empty).
• A lab activity's scenario_id must be a real, existing scenario id.
• An assessment/capstone activity's assessment_definition_id must be a real, active assessment_definitions row.
• Walk the module once as a self-paced student end to end (lesson → ... → lab → reflection), and once through the instructor Curriculum view, before shipping — this is what e2e-phase6a.js and infra/scripts/drills/test-phase6a-course-rehearsal.js automate for the gold module; extend one of them (or add a new phase-scoped test) for future modules rather than skipping this step.