Align course structure and pedagogy docs - #6
Conversation
There was a problem hiding this comment.
Code Review
This pull request updates the repository's documentation to align with the current course structure, including the addition of 'Course Phases' tables and the refinement of module roles and goals. Key changes involve updating crate descriptions from 'workspace crates' to 'real crates,' revising terminology for clarity and inclusivity, and expanding the lesson plans for the MLP and Attention modules. Review feedback highlights several opportunities to improve consistency across the documentation, specifically regarding the alignment of columns and terminology within the newly introduced tables and the standardization of technical terms like 'attention weights.'
| | Phase | Modules | Status | Learner checkpoint | | ||
| | --- | --- | --- | --- | | ||
| | Orientation | 0 Foundations, 1 Vectors | Active | Read ML notation and vector code without losing the plain-English meaning. | | ||
| | First trainable system | 2 Neuron, 3 Learning | Active | Explain one model, one backward pass, one optimizer step, and one token-target bridge. | | ||
| | Bridge to architecture | 4 MLP, 5 Attention | Planned | Connect training to layers, hidden activations, token interactions, and attention scores. | | ||
| | Architecture preview | 6 Transformer | Active preview | Read the encoder path and understand why full Transformer training needs more machinery. | |
There was a problem hiding this comment.
This table is missing the "Repo folders" column that is included in the lessons/COURSE-STRUCTURE.md version. Since the mapping between course modules and folder numbers is non-trivial (e.g., Module 0 maps to 01-foundations), adding this column here would help users navigate the repository more easily from the root README.
| | Orientation | [01-foundations](01-foundations/README.md), [02-vectors](02-vectors/README.md) | Authored | Read notation, vectors, dot products, sigmoid, loss, and update rules. | | ||
| | First trainable system | [03-neuron](03-neuron/README.md), [04-learning](04-learning/README.md) | Authored | Trace a neuron, compute gradients, train across a dataset, and explain token targets. | | ||
| | Bridge to architecture | [05-mlp](05-mlp/README.md), [06-attention](06-attention/README.md) | Planned | Move from one neuron to layers, then from token vectors to attention scores. | | ||
| | Architecture preview | [07-transformer](07-transformer/README.md) | Authored preview | Read the Transformer encoder path before the middle bridge is complete. | |
There was a problem hiding this comment.
The "Status" column uses "Authored" and "Authored preview" here, but the root README.md and the canonical lessons/COURSE-STRUCTURE.md use "Active" and "Active preview". Standardizing these terms across all "Course Phases" tables improves consistency across the documentation.
| | Orientation | [01-foundations](01-foundations/README.md), [02-vectors](02-vectors/README.md) | Authored | Read notation, vectors, dot products, sigmoid, loss, and update rules. | | |
| | First trainable system | [03-neuron](03-neuron/README.md), [04-learning](04-learning/README.md) | Authored | Trace a neuron, compute gradients, train across a dataset, and explain token targets. | | |
| | Bridge to architecture | [05-mlp](05-mlp/README.md), [06-attention](06-attention/README.md) | Planned | Move from one neuron to layers, then from token vectors to attention scores. | | |
| | Architecture preview | [07-transformer](07-transformer/README.md) | Authored preview | Read the Transformer encoder path before the middle bridge is complete. | | |
| | Orientation | [01-foundations](01-foundations/README.md), [02-vectors](02-vectors/README.md) | Active | Read notation, vectors, dot products, sigmoid, loss, and update rules. | | |
| | First trainable system | [03-neuron](03-neuron/README.md), [04-learning](04-learning/README.md) | Active | Trace a neuron, compute gradients, train across a dataset, and explain token targets. | | |
| | Bridge to architecture | [05-mlp](05-mlp/README.md), [06-attention](06-attention/README.md) | Planned | Move from one neuron to layers, then from token vectors to attention scores. | | |
| | Architecture preview | [07-transformer](07-transformer/README.md) | Active preview | Read the Transformer encoder path before the middle bridge is complete. | |
| | Phase | Course modules | Repo folders | Status | | ||
| | --- | --- | --- | --- | | ||
| | Orientation | Modules 0-1 | `01-foundations`, `02-vectors` | Active | | ||
| | First trainable system | Modules 2-3 | `03-neuron`, `04-learning` | Active | | ||
| | Bridge to architecture | Modules 4-5 | `05-mlp`, `06-attention` | Planned | | ||
| | Architecture preview | Module 6 | `07-transformer` | Active preview | |
There was a problem hiding this comment.
This table is missing the "Checkpoint" column present in the other two "Course Phases" tables. Additionally, the column order differs from the versions in README.md and lessons/README.md. Aligning the columns and their order across all three files would better support the PR's goal of aligning the course structure documentation.
| 1. a narrative lesson about the problem, the paper, and the full encoder rhythm | ||
| 2. a typed Rust lesson about semantic newtypes, `thiserror`, and architecture visibility | ||
| 3. an ADHD-friendly chunk ladder using `English -> Algebra -> Rust` | ||
| 3. a low-cognitive-load chunk ladder using `English -> Algebra -> Rust` |
| ## Goal | ||
|
|
||
| Introduce token representations, projections, and attention scores. | ||
| Introduce token representations, projections, masks, attention scores, normalized weights, and weighted sums. |
There was a problem hiding this comment.
Use "attention weights" instead of "normalized weights" to be consistent with the terminology used in the "Planned Outcome" section and standard ML literature.
| Introduce token representations, projections, masks, attention scores, normalized weights, and weighted sums. | |
| Introduce token representations, projections, masks, attention scores, attention weights, and weighted sums. |
Summary
Testing
Need help on this PR? Tag
@codesmithwith what you need.