Skip to content

Every notebook teaches one concept clearly, on real data #44

Description

@project-delphi

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.

  • 00 · Setup and welcome
  • 01 · What a tensor is
  • 02 · Thinking in N dimensions
  • 03 · Indexing and broadcasting real data
  • 04 · Reshape and transpose real images
  • 05 · Video pipeline design
  • 06 · Contraction with einsum
  • 07 · Inverses and the pseudoinverse
  • 08 · Recursion with matrices and vectors
  • 09 · Convolution and deconvolution
  • 10 · Tucker decomposition on real data
  • 11 · Wrap-up and take-homes

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:

  • Learning outcomes signed off across all twelve sections
  • Before-and-after screenshots of each notebook posted as a comment on this
    issue. The notebooks are committed with no outputs, so screenshots are the
    only record anyone has of what a run actually looks like.

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

blockedWaiting on another issue before work can startcontentTeaching content: accuracy, examples, referencesenhancementNew feature or requestnotebooksnotebooks/ and scripts/content.py

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions