Learning Machine: A Question-Driven ML Handbook Built as Jupyter Notebooks

The problem: ML explanations that are too long, too dense, or too tangled

The README states the motivation directly. Most machine learning resources online are, in its words, either too long, too math heavy, or too confusing, and the book aims to be concise but easy to grasp. The stated audience is learners who want to quickly grasp an idea without diving deep, described as a handbook for people who want to preserve their time. The disclaimer adds one prerequisite: at least some basic understanding of programming. Nothing in the material suggests prior ML coursework is assumed, though the book accompanies Hung-Yi Lee's 2021 spring machine learning course, so a reader following that course will get the most out of the ordering. The framing is unusual for a technical book: the README says it was created while the author was a teaching assistant, aggregating students' questions into a book. That origin explains the shape of the index, which reads like a list of things people actually got stuck on rather than a syllabus ordered by mathematical dependency.

How the book is assembled: notebooks, an index, and a rendered site

The repository is primarily Jupyter Notebook content, and the README's index is a direct map of the file tree. Each entry points at a .ipynb path under book/, for example book/basics/data/data.ipynb, book/layers/transformer/attn/self-attn.ipynb, and book/reinforce/value/q-learning.ipynb. Top-level groupings are Getting Started, Common Tasks, Common Building Blocks, Other Things To Notice, Generative Models, Improving Models, Reuse Existing Models, Beyond Supervised Training, and Reinforcement Learning. There is no Python package, no CLI, and no build system described in the material. The homepage is a rendered version of the same notebooks, and the README links a GitHub Pages address as well, so the intended reading mode is a browser, with the notebooks available when you want to inspect or run the cells yourself. One detail worth flagging: the index contains at least two broken paths. The ReLU entry links to book/reinforce/value/q-learning.ipynb, which is the Q Learning notebook, and Knowledge Distillation and Decision Tree are written without the leading ./book/ prefix used by their siblings. Treat the index as a guide, not as a verified manifest.

Getting it running locally

Because the deliverable is notebooks, running it means running Jupyter against a clone. The README does not give an install section, so the commands below follow from the repository layout rather than from documented instructions. Clone the repository, then start Jupyter from the repository root so the relative image and asset paths inside the notebooks, such as ./book/images/logo.png, resolve: git clone https://github.com/rentruewang/learning-machine.git, then cd learning-machine, then jupyter notebook or jupyter lab. Open book/basics/basics.ipynb as the entry point, since the index lists it first under Getting Started. There is no requirements.txt, environment.yml, or pyproject.toml mentioned in the supplied material, so any notebook that imports a framework will need that framework installed by you, and I cannot confirm from the material which notebooks are executable and which are prose with diagrams. The homepage is the lower-friction option if you only want to read. Note also that the README marks the project as archived in its own first section, which is a statement about intent, not about the repository's GitHub archived flag.

What the coverage actually includes

The breadth is wider than the concise framing suggests. Getting Started covers data, model, loss function, approximation, and gradients, with separate notebooks for the loss function derivative and back propagation. Common Building Blocks runs from linear layers and their gradients through convolution, recurrent layers with LSTM and GRU, embedding, dropout, normalization, padding, pooling, and a transformer subtree containing attention, self attention, a comparison against RNN, training, teacher forcing, tokenization, and a without training page. Generative Models covers autoencoders including a variational variant, GANs, and Gaussian mixture models. Reinforcement Learning covers state, agent, action, reward, online versus offline, value and Q learning, policy and policy gradient, and actor critic. Two structural choices are worth noting. First, the transformer section includes a versus RNN comparison and a no-training page, which is the kind of question a student actually asks. Second, Other Things To Notice collects batch size, gradient norm, saddle points, learning rate, optimizer, overfit, and underfit into one group, which puts training-dynamics questions in one place instead of scattering them across layer pages.

Where the handbook format breaks down

The archive notice is the first limitation and the README states it plainly: the author does not see an update in the near future and now works mainly on aioway, a deep learning algorithm compiler. The book accompanies a 2021 spring course, so anything that moved after that date is not reflected. Second, concision is a trade-off, not a free win. A reader who needs to derive back propagation or implement attention from scratch will find the notebook too thin, and the README's own framing concedes the book is for people who do not want to dive deep. Third, the index has the broken links noted above, which means a reader navigating by the README can land on the wrong notebook without realizing it. Fourth, the disclaimer sets a programming prerequisite but says nothing about math prerequisites, and a book that deliberately avoids math will not prepare you to read a paper. Fifth, there is no stated versioning, no changelog, and no releases were retrieved, so there is no way to tell from the material which notebook was last touched when. This is the wrong tool if you need a maintained reference, runnable training pipelines, or coverage of anything released after the course it accompanies.

Compared with a full course or a framework tutorial

The obvious alternative for the same learner is the course this book accompanies, Machine Learning with Hung-Yi Lee, linked from the README. The difference in approach is scope and mode: the course is a sequence of lectures with assignments, while the book is a set of short notebooks organized around questions, and the README presents it as a companion rather than a substitute. A second alternative is a framework's own tutorials, which teach the API alongside the concept and give you code you can run and modify immediately. The book inverts that: it explains the concept first and keeps the code minimal, which is faster for orientation and worse for building something. If your goal is to ship a model, a framework tutorial gets you there sooner. If your goal is to understand why a layer exists before you call it, the question-driven ordering here is the more direct path, and the versus RNN and no-training pages are examples of the comparison-style content a tutorial usually omits.

Maintenance cost and licence

The maintenance cost is close to zero because the project is not maintained. The README's archive section states there is no update in the near future, so there is no upgrade treadmill, no breaking changes to track, and no dependency pinning to reconcile. That is also the risk: if a notebook's explanation conflicts with a current framework behavior, nothing in the repository will correct it. The licence is Apache-2.0, which permits commercial and private use, modification, and redistribution provided you keep the licence and notice files and state significant changes; it also includes a patent grant and a patent retaliation clause. Apache-2.0 does not grant trademark rights, so the project name and logo, which the README says was made with Inkscape from a meme, are not covered by the code licence. None of this is legal advice; read LICENSE and NOTICE in the repository if you plan to redistribute the notebooks, for example as internal training material.

Editorial conclusion

Adopt it if you already know some programming and want a fast, question-shaped orientation to a topic before committing to a longer source. Do not adopt it if you need a maintained reference, runnable training code, or material newer than the 2021 course it accompanies; the README states the author does not see an update in the near future and points current work at aioway. Before relying on any page, open the corresponding notebook under book/, confirm it is not a stub, and check whether the topic you need exists in the index at all. Transformer and reinforcement learning coverage is present, but a missing index entry means the book simply does not cover it.

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. rentruewang/learning-machine on GitHub