github-starred/cs249r_book
2
0
Fork 0
mirror of https://github.com/harvard-edge/cs249r_book.git synced 2026-07-17 08:28:07 -05:00
Code Issues 276 Packages Projects Releases 26 Wiki Activity

[GH-ISSUE #1822] StaffML: link each question to recommended textbook reading (topic → chapter) #35279

New Issue
Open
opened 2026-07-15 22:41:15 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-07-15 22:41:15 -05:00
Owner
Copy Link

Originally created by @profvjreddi on GitHub (May 29, 2026).
Original GitHub issue: https://github.com/harvard-edge/cs249r_book/issues/1822

Idea

When a StaffML question is shown, offer a "want to learn more about this?" pointer back into the textbook — a go-deeper link tied to the question's topic, not an answer key. The textbook is where StaffML's content is sourced, so this closes the loop from practice back to the book (Vol 1 + Vol 2). Future versions could broaden to other sources; v1 is book-only.

Key finding — the plumbing is already dormant

A Resource type and a details.resources field already exist in the question schema, the TS types, and the corpus bundle — but 0 of the ~10,700 questions populate it and nothing renders it. Footer.tsx documents the reason it was parked: "Per-question book links are deferred until mlsysbook.ai URLs stabilize." This issue is to un-defer it.

Approach (low-effort, high-coverage)

Don't hand-author a reference per question. Every question already carries a topic (one of 87 curated) and competency_area (one of 13). Map the 87 topics → chapters once and derive each question's reference automatically at build time.

  • Source of truth: a single topic_chapter_map.yaml (~87 rows: topic → primary chapter + optional "also see").
  • Vault build joins topic → chapter and emits book_refs into the summary bundle (renders synchronously, no extra fetch).
  • details.resources stays available for per-question overrides later.

URL stability (the original blocker — resolved)

The live chapter URL pattern is stable and verified (HTTP 200):
https://mlsysbook.ai/vol{N}/contents/vol{N}/{chapter}/{chapter}.html
Link at chapter granularity for v1 — section anchors carry auto-generated hash suffixes that regenerate on rebuild. Add a build-time link-checker so a mapped chapter that doesn't exist fails the build (turns "wait until URLs stabilize" into "URLs are enforced valid").

Pedagogy

Show the reading after the attempt, not before — a "Learn more" card below the revealed solution. Optionally, on a wrong answer, surface the prerequisite topic's chapter (the taxonomy already encodes prerequisite edges).

Phasing

  1. topic_chapter_map.yaml + build join + chapter-level "Learn more" card + link-checker.
  2. Prerequisite-on-wrong-answer; per-question resources overrides.
  3. Bidirectional chapter → practice links; multi-source (papers/docs).

Filed as a future enhancement; a first-pass 87-row topic→chapter draft already exists to seed step 1.

Originally created by @profvjreddi on GitHub (May 29, 2026). Original GitHub issue: https://github.com/harvard-edge/cs249r_book/issues/1822 ## Idea When a StaffML question is shown, offer a "want to learn more about this?" pointer back into the textbook — a *go-deeper* link tied to the question's **topic**, not an answer key. The textbook is where StaffML's content is sourced, so this closes the loop from practice back to the book (Vol 1 + Vol 2). Future versions could broaden to other sources; v1 is book-only. ## Key finding — the plumbing is already dormant A `Resource` type and a `details.resources` field already exist in the question schema, the TS types, and the corpus bundle — but **0 of the ~10,700 questions populate it** and nothing renders it. `Footer.tsx` documents the reason it was parked: *"Per-question book links are deferred until mlsysbook.ai URLs stabilize."* This issue is to un-defer it. ## Approach (low-effort, high-coverage) Don't hand-author a reference per question. Every question already carries a `topic` (one of 87 curated) and `competency_area` (one of 13). **Map the 87 topics → chapters once** and derive each question's reference automatically at build time. - Source of truth: a single `topic_chapter_map.yaml` (~87 rows: topic → primary chapter + optional "also see"). - Vault build joins topic → chapter and emits `book_refs` into the summary bundle (renders synchronously, no extra fetch). - `details.resources` stays available for per-question overrides later. ## URL stability (the original blocker — resolved) The live chapter URL pattern is stable and verified (HTTP 200): `https://mlsysbook.ai/vol{N}/contents/vol{N}/{chapter}/{chapter}.html` Link at **chapter** granularity for v1 — section anchors carry auto-generated hash suffixes that regenerate on rebuild. Add a build-time link-checker so a mapped chapter that doesn't exist fails the build (turns "wait until URLs stabilize" into "URLs are enforced valid"). ## Pedagogy Show the reading **after** the attempt, not before — a "Learn more" card below the revealed solution. Optionally, on a wrong answer, surface the **prerequisite** topic's chapter (the taxonomy already encodes prerequisite edges). ## Phasing 1. `topic_chapter_map.yaml` + build join + chapter-level "Learn more" card + link-checker. 2. Prerequisite-on-wrong-answer; per-question `resources` overrides. 3. Bidirectional chapter → practice links; multi-source (papers/docs). _Filed as a future enhancement; a first-pass 87-row topic→chapter draft already exists to seed step 1._
GiteaMirror added the area: staffmlarea: booktype: improvement labels 2026-07-15 22:41:16 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area: book
area: collabs
area: kits
area: labs
area: socratiq
area: staffml
area: tinytorch
area: tools
area: website
bug
dependencies
format: epub
format: pdf
javascript
link-health
link-rot
priority-high
pull-request
Mirrored from GitHub Pull Request
 staffml
type: bug
type: citation
type: code
type: errata
type: improvement
type: new
type: question
vault-sli
No Label area: book area: staffml type: improvement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/cs249r_book#35279
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?