Blocked by #43 for landing changes — until the Colab round trip
works, every edit here has to be retyped into scripts/content.py. The
learning-outcome review below needs no pipeline and can start immediately.
The problem
Twelve notebooks, built at different times, and it shows.
Structure drifts. §03, §04, §06, §09 and §10 close with ## What just happened; §08 has no close at all. The exercise triple — markdown prompt, a
# TODO cell, a folded #@title Solution cell — is the pattern, but §00, §02,
§05 and §08 carry two solutions where the others carry three.
Objectives are uneven and invisible. They exist only as the objectives
list per section in scripts/content.py, and surface only under ## What you will be able to do inside the notebook itself — nowhere on the site, nowhere in
either deck. §04 has three; §11 has seven and they read as take-home
descriptions rather than learning outcomes. All are English-only, unlike titles
and summaries, which are bilingual in _variables.yml.
"All the data is real" is not currently true. Notebook 00 states plainly:
"Nothing in this workshop is invented with random numbers." But
- §02 is fully synthetic —
np.zeros shapes and rng.permutation(8). Defensible
for a discussion block, but then the claim in 00 needs scoping.
- §07 Exercise 1 and Exercise 3 use
rng.standard_normal((5, 3))
(scripts/content.py:1203) and rng.standard_normal((4, 3, 5)) (:1234,
:1325) — in the one section whose entire pitch is 20,433 real housing
equations.
- §08's Fibonacci and power-iteration demos (
:1382, :1391) and the RNN
skeleton (:1479–:1481) are random.
- §11 take-home B (attention) is
np.random.randn (:2160–:2162), and it
reaches for legacy np.random.seed(6) rather than the rng used everywhere
else in the workshop.
The ask
Work each section until it teaches one concept clearly, with code and real data.
Improve it with Gemini in Colab; land it per #43.
A box is done when all of these hold for that section:
- one concept, named in the objectives, taught end to end
- a real dataset — or one explicit sentence saying why synthetic is the right
choice here
- the standard shape: header and objectives → Setup → Why this matters →
Exercise ×N (markdown → # TODO → folded solution) → What just happened →
footer
- the Kahoot footer after 04, 07 and 10;
## Done with this section otherwise
- a Gemini pass over both the prose and the exercises
Then, once all twelve are through:
Constraints
And the one that fails silently: notebooks/*.ipynb are resources: in
_quarto.yml, not render: targets. A notebook change committed without a
re-render leaves docs/notebooks/ serving the old copy and nothing goes red
— scripts/compare_render.py only walks *.html. This has already happened
once, to nine of the twelve at the same time. Re-render after any notebook
change.
uv run --with pyyaml,nbformat python scripts/gen_notebooks.py
uv run --with pyyaml,nbformat python scripts/check_links.py
quarto render # Quarto 1.6.40 exactly — a different version reds the gate
The problem
Twelve notebooks, built at different times, and it shows.
Structure drifts. §03, §04, §06, §09 and §10 close with
## What just happened; §08 has no close at all. The exercise triple — markdown prompt, a# TODOcell, a folded#@title Solutioncell — is the pattern, but §00, §02,§05 and §08 carry two solutions where the others carry three.
Objectives are uneven and invisible. They exist only as the
objectiveslist per section in
scripts/content.py, and surface only under## What you will be able to doinside the notebook itself — nowhere on the site, nowhere ineither deck. §04 has three; §11 has seven and they read as take-home
descriptions rather than learning outcomes. All are English-only, unlike titles
and summaries, which are bilingual in
_variables.yml."All the data is real" is not currently true. Notebook 00 states plainly:
"Nothing in this workshop is invented with random numbers." But
np.zerosshapes andrng.permutation(8). Defensiblefor a discussion block, but then the claim in 00 needs scoping.
rng.standard_normal((5, 3))(
scripts/content.py:1203) andrng.standard_normal((4, 3, 5))(:1234,:1325) — in the one section whose entire pitch is 20,433 real housingequations.
:1382,:1391) and the RNNskeleton (
:1479–:1481) are random.np.random.randn(:2160–:2162), and itreaches for legacy
np.random.seed(6)rather than therngused everywhereelse in the workshop.
The ask
Work each section until it teaches one concept clearly, with code and real data.
Improve it with Gemini in Colab; land it per #43.
A box is done when all of these hold for that section:
choice here
Exercise ×N (markdown →
# TODO→ folded solution) → What just happened →footer
## Done with this sectionotherwiseThen, once all twelve are through:
issue. The notebooks are committed with no outputs, so screenshots are the
only record anyone has of what a run actually looks like.
Constraints
.ipynbagainst the current pipeline — CI fails byte-exact.ipywidgetsneedsenable_custom_widget_manager()on Colab.and depends on no other notebook having run.
checklist and names the commented-out matplotlib at
scripts/content.py:639,:1317and:1656. Don't duplicate it here.And the one that fails silently:
notebooks/*.ipynbareresources:in_quarto.yml, notrender:targets. A notebook change committed without are-render leaves
docs/notebooks/serving the old copy and nothing goes red—
scripts/compare_render.pyonly walks*.html. This has already happenedonce, to nine of the twelve at the same time. Re-render after any notebook
change.