ced4568andClaude Sonnet 5
fd38d06055
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]>
127 lines
6.7 KiB
Markdown
127 lines
6.7 KiB
Markdown
# 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.
|