docs(phase6a): document RootNode course foundation
COURSE_AUTHORING_STANDARD.md — the standard every future lesson/module must follow (target learner, prerequisites, measurable objectives, concept-before-lab, instructor notes, terminology, versioning, review requirements), grounded in the gold-standard module as the reference implementation. PHASE6A_ROOT_COURSE_FOUNDATION.md — the phase summary: youth-ladder context, the Google Workspace status already recorded in Phase 5C's own docs, architecture/build summary, honest content states, test results, explicit non-goals, and known limitations/Phase 6B recommendations. Updated ENGINEERING_SOP.md (new Phase 6A section + a curriculum-content cross-reference), REMOTE_AND_SELF_PACED_ARCHITECTURE.md (a 7th closed gap: self-paced enrollment now resolves to a real course tree, not just a scenario list), LAB_ARCHITECTURE.md (Phase 6A reuses the disposable Lab unmodified, verified by a real rehearsal), and platform/README.md (course model in the api/ summary, new e2e suite descriptions for 5A/5B/5C/6A which were missing entirely, and the real-Lab rehearsal script). Co-Authored-By: Claude Sonnet 5 <[email protected]>
This commit is contained in:
@@ -0,0 +1,126 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user