Skip to content

Align course structure and pedagogy docs - #6

Merged
hghalebi merged 1 commit into
mainfrom
rd/add-training-module
Apr 28, 2026
Merged

hghalebi merged 1 commit into
mainfrom
rd/add-training-module

Conversation

@hghalebi

@hghalebi hghalebi commented Apr 28, 2026

Copy link
Copy Markdown
Owner

Summary

  • align the root README, lesson index, and course structure guide around one four-phase course map
  • correct code-artifact ownership now that the neuron crate is active
  • tighten the planned MLP/Attention roadmap language and placeholder crate wording

Testing

  • python3 scripts/check_course_content.py
  • python3 scripts/check_lesson_rust_snippets.py
  • cargo fmt --manifest-path code/neuron/Cargo.toml --check
  • cargo clippy --manifest-path code/neuron/Cargo.toml --all-targets --all-features
  • cargo test --manifest-path code/neuron/Cargo.toml
  • cargo fmt --manifest-path code/transformer/Cargo.toml --check
  • cargo clippy --manifest-path code/transformer/Cargo.toml --all-targets --all-features
  • cargo test --manifest-path code/transformer/Cargo.toml

View in Codesmith
Need help on this PR? Tag @codesmith with what you need.

  • Let Codesmith autofix CI failures and bot reviews

@hghalebi
hghalebi merged commit c55801d into main Apr 28, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.'

Comment thread README.md
Comment on lines +120 to +125
| 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. |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Comment thread lessons/README.md
Comment on lines +27 to +30
| 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. |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
| 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. |

Comment on lines +33 to +38
| 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 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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`

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Consider adding backticks around English -> Algebra -> Rust to maintain consistency with how this pattern is referenced in the root README.md and lessons/COURSE-STRUCTURE.md.

## Goal

Introduce token representations, projections, and attention scores.
Introduce token representations, projections, masks, attention scores, normalized weights, and weighted sums.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Use "attention weights" instead of "normalized weights" to be consistent with the terminology used in the "Planned Outcome" section and standard ML literature.

Suggested change
Introduce token representations, projections, masks, attention scores, normalized weights, and weighted sums.
Introduce token representations, projections, masks, attention scores, attention weights, and weighted sums.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant