Read the chapter READMEs as a student would, and reorder them for one - #93
Merged
Conversation
Chapter 2 committed four figures and displayed none of them. The section that would have shown them was a table of captions, and its own opening sentence said the reason they exist is that the convention "is far easier to see than to read" -- then handed the reader a table describing four pictures they could not see, one line away from the files. They are good pictures and they carry the chapter's three real traps: - frame_chain: NED is a handedness-preserving swap-and-flip of ENU, not a rotation, with the same dashed ENU reference behind all three panels. - euler_convention: roll turns about Y and pitch about X here, which is not the aerospace default, with each panel's axis of rotation drawn. - passive_vs_active: Chapter 2's C rotates coordinates, Chapter 6's body-to-map rotates the vector; they differ by a transpose, so at yaw = 50 degrees the two answers sit 100 degrees apart. - gimbal_lock: the singularity is at roll = +/-90, not pitch, and the bottom row proves it -- (90, 0, 30) and (90, -30, 0) give matrices agreeing to 3.1e-17. Each now appears with a caption that states the takeaway rather than naming the file. The equation numbers stay, after the sentence rather than instead of it. Also dropped `--no-show` from the Quick Start line. Since figures stopped opening windows by default, telling a first-time reader to suppress a window they were never going to get is noise. The flag still works; it is now redundant with IPIN_SHOW_FIGURES, which is worth revisiting separately. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Seven chapters ship a notebook, each with a Colab bootstrap cell that clones and installs the repository so a reader with only a browser can run the chapter. Measured: **0 of 7 chapter READMEs mentioned it**, and 0 of 7 carried a Colab link. The badges existed only in the top-level README's table. Where readers arrive is what makes this more than a missing link. Someone following a reference from the book, or clicking into ch3_estimators/ from the repository listing, lands on the chapter README and never sees the front page. For them the runnable version did not exist. It also broke the step in the middle of how anyone actually learns from these: see a figure, change a parameter, see what happened, then read the equation. A reader who has just been shown a figure and wants to change something had, from the chapter README, nowhere to do it -- and changing something to see what happens is most of what these examples are for. The badge goes above the Overview, with one line saying what it is for, because a link to the interactive version is worth nothing three screens down past the equation tables. tests/docs/test_chapters_link_their_notebook.py holds both the presence and the position, and checks the badge points at the chapter's own notebook -- the names do not match for ch4, whose notebook is ch4_rf_positioning.ipynb. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A reader met the first figure between 28% and 72% of the way down a chapter
README, and in Chapter 2 never. They meet it at 4-9% now, in six of seven.
**Almost none of this was writing new content.** The figures were already there
and already positioned correctly -- each chapter's most compelling early section
already argued for one and then withheld it. Seven more figures across four
chapters were named in prose and never displayed, and every one sat in the
section immediately after Quick Start:
ch3 ch3_particle_bimodal "Why the particle filter, really"
ch4 ch4_dop_geometry "Dilution of precision", whose own text says
DOP "is what a single number cannot convey"
ch4 ch4_initial_guess_basin "The initial guess, and why it is usually the
wrong thing to blame"
ch5 ch5_walk_posterior "The posterior along a walk, and how it fails"
ch8 ch8_anchor_outage "Anchor Outage: where the difference shows"
ch8 temporal_calibration_demo, tuning_robust_demo -- in a Figure Gallery
that described them without showing them
Chapter 7 had a fourth instance my first scan missed, because its table names
the files without extensions: four figures of Section 7.3 described in a table
and never drawn. That table is now the four figures, each carrying the sentence
that used to be its row -- the same shape as Chapter 2's fix. A grep sees the
spellings you thought to look for.
Two orderings changed as well:
- Equation Reference moves below the figures and examples in all seven, to just
above the Architecture boilerplate. In ch4 that section is 414 lines, 44% of
the chapter, and it stood between Quick Start and every picture.
- ch6's Quick Start moves above "Frame Conventions" and "EKF State Vector". A
reader had to get through two dense convention sections before being told how
to run anything. It also gains comparison_trajectories as a chapter opener:
IMU alone ends 90 m from a walk that never left 30 m, and the zoom panel
beside it is where ZUPT, odometry and PDR become distinguishable at all.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
**Chapter 3's left panel showed one dot beside a seven-entry legend.** Linear
LS, Gauss-Newton and LM all land within about 5 cm of the truth on clean data,
so at the scale that shows the anchors they overlap completely -- and the
difference between those three solvers is the panel's entire subject.
It gets the fix Chapter 6's comparison figure already uses: keep the overview,
put the part worth seeing beside it. A 20 cm inset, with connector lines to the
region it magnifies, now shows the truth, Linear LS 4.5 cm away, and
Gauss-Newton and LM landing on exactly the same point -- drawn as a small
filled square inside a larger hollow diamond, so "they agree exactly" is
something you can see rather than infer.
**Both titles now state the conclusion instead of naming the section.**
before "Examples 1-4: LS Methods (Clean Data)
Gauss-Newton (Eq. 3.52) & LM (Eq. 3.53, Alg. 3.2)"
after "On clean data all three solvers agree to centimetres
(inset: a 20 cm window on the same estimates)"
before "Example 5: Robust LS with Table 3.1 Estimators"
after "One corrupted anchor drags plain least squares off the truth
while every robust loss in Table 3.1 ignores it"
Chapter 6's comparison, newly promoted to that chapter's opening screen, gets
the same treatment: "Chapter 6 Comparison: All Dead Reckoning Methods" becomes
"IMU alone drifts to 54 m RMSE; ZUPT cuts it to 8.8, odometry and PDR to under
a metre".
**Two claims were wrong on the way and are worth recording.** The first title
draft said the inset was magnified 60x; the arithmetic is 21.6x, so it states
the window size instead -- a fact that stays true if someone resizes the inset.
The second draft said "every correction keeps it inside", which the picture
contradicts: ZUPT does leave the box. Both are replaced by numbers the example
actually prints. The same correction applied to the README caption beside it,
which had claimed "about 90 m" for a drift whose measured RMSE is 54 m.
Titles elsewhere are left alone. Several already state their takeaway -- ch4's
"An initial-guess problem that is not about the initial guess" is the model --
and retitling every figure means regenerating every figure, which is its own
change.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Chapter 2 was 57% text-only boilerplate, dominated by a 103-line console
transcript in a document that had no figures at all. Chapter 7 carried a
206-line pipeline description between the datasets and the results.
**Collapsed rather than moved, and that is the point.** The transcripts are
pinned by tests/docs/test_readme_example_output.py, which globs
`ch*_*/README.md`; relocating them to docs/ would have taken them out of that
glob and quietly stopped them being checked. A `<details>` block keeps every
line in the file and in the guard -- the parser looks one or two lines above a
fence for its marker, so the wrapper is invisible to it. Verified: 29 tests
collected before and after.
**Only four transcripts were collapsed, out of 22.** Blanket-collapsing would
have been the wrong reading of "less is more": most of these are six-line
result tables sitting beside the sentence that interprets them, which is
exactly what a reader wants. Measured, only four run past 25 lines --
ch2's 103, ch7's pose graph at 36, ch8's LC and TC at 29 and 28 -- and those
are the ones that stop being evidence and start being scenery.
ch2_coords 109 of 360 lines now behind a summary (30%)
ch7_slam 249 of 907 (27%)
ch8_sensor_fusion 69 of 860 (8%)
Chapter 7's section keeps its heading and gains three lines saying what is
inside it and who it is for, so a reader can decide without expanding.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Audited all seven chapter READMEs by rendering them and opening the figures,
against how a student actually works: see the picture, change something, then
read the equation. The content is strong. The order was the inverse of that,
and one chapter withheld its pictures entirely.
Five commits, one per change.
1. Chapter 2 showed none of its four figures
It had a section called
## Figureswhose opening sentence was "that is fareasier to see than to read" — followed by a table describing four pictures
the reader could not see, one line away from the files.
They are good pictures and they carry the chapter's three real traps: NED is a
swap-and-flip of ENU rather than a rotation; roll turns about Y here, which
is not the aerospace default; passive and active differ by a transpose, so at
yaw = 50° the two answers sit 100° apart; and the singularity is at
roll = ±90°, proved in the figure by two different inputs whose matrices
agree to 3.1e-17.
Each is now shown, with a caption that states the takeaway instead of naming
the file.
2. The "change something" step was unreachable
Seven notebooks, each with a Colab bootstrap cell that clones and installs the
repo. Not one chapter README mentioned it. A reader arriving from the book
or from the repository listing never sees the front page's table, so for them
the runnable version did not exist.
Badge above the Overview in all seven, held by
tests/docs/test_chapters_link_their_notebook.py— presence and position,since a link three screens down past the equation tables is worth nothing.
3. The pictures now come before the algebra
Almost none of this was new content. Each chapter's most compelling early
section already argued for a figure and then withheld it — and every one of the
seven sat immediately after Quick Start:
ch3_particle_bimodal— "Why the particle filter, really"ch4_dop_geometry— a section whose own text says DOP "is what a singlenumber cannot convey"
ch4_initial_guess_basin, ch5ch5_walk_posterior, ch8ch8_anchor_outage,plus two in a Figure Gallery that described them without showing them
Chapter 7 had a fourth instance my first scan missed, because its table names
files without extensions. Four figures of Section 7.3, described and never
drawn; that table is now the four figures, each carrying the sentence that used
to be its row.
Two orderings changed too:
Equation Referencemoves below the figures in allseven (in ch4 it is 414 lines, 44% of the chapter, standing between Quick Start
and every picture), and ch6's Quick Start moves above two dense convention
sections a reader had to cross before being told how to run anything.
4. Two figures now teach what they were drawn to teach
Chapter 3's left panel showed one dot beside a seven-entry legend — Linear
LS, Gauss-Newton and LM land within 5 cm on clean data, and the difference
between them is the panel's whole subject. It gets the fix ch6's comparison
already used: a 20 cm inset with connector lines, where Gauss-Newton and LM are
drawn as a filled square inside a hollow diamond, so "they agree exactly" is
visible rather than inferred.
Titles changed from labels to conclusions —
"Examples 1-4: LS Methods (Clean Data)"becomes"On clean data all three solvers agree to centimetres".Two of my own drafts were wrong and are recorded as such: a title claiming
60xmagnification (the arithmetic is 21.6x, so it states the window sizeinstead), and
"every correction keeps it inside"— which the picturecontradicts, since ZUPT does leave the box. Both replaced with numbers the
example prints. Same correction applied to a caption claiming "about 90 m" for
a drift whose measured RMSE is 54 m.
5. Four walls of text folded away
ch2 was 57% text-only boilerplate, dominated by a 103-line transcript in a
document with no figures.
Collapsed, not moved, and that is load-bearing. The transcripts are pinned
by
test_readme_example_output.py, which globsch*_*/README.md— relocatingthem to
docs/would have quietly stopped them being checked.<details>keepsevery line in the file and in the guard; verified 29 tests collected before and
after.
Only 4 of 22 transcripts were collapsed. Blanket-collapsing would have been
the wrong reading of "less is more": most are six-line result tables beside the
sentence that interprets them. Only four run past 25 lines.
Verification
Full suite 3106 passed, 21 skipped, tree clean. Every README transcript
still matches, every committed figure still produced. The two regenerated
figures were opened and looked at before being committed.
🤖 Generated with Claude Code