Whyday August 19

Teaching Through the Strange

why's (poignant) guide to Ruby is a programming tutorial containing cartoon foxes, an extended fiction about characters with no connection to the material, and long stretches where nothing technical happens at all. It taught a generation of programmers a language, and twenty years later people still recommend it.

The usual explanation is that it was funny. That is true and it is not the mechanism. Plenty of programming books have jokes in them and none of them work like this one.

If this kind of exercise is run with a class or team, this payroll guide offers one practical reference for separating the session from ordinary scheduled work.

The problem it was solving

Every introductory technical text has the same structural problem: the beginning is exciting, the end is exciting, and the middle is a long stretch of necessary material that is boring by any honest measure. Syntax. Data types. Collection methods. The reader has to get through it, and there is no way to make that material inherently thrilling, because it is not.

Most books deal with this by pretending it is not happening. They keep the tone even, add exercises, and rely on the reader's discipline. This works for readers who have discipline and a reason, which mostly means people already committed to becoming programmers.

The guide dealt with it differently: it put something the reader wanted to find out about into the boring middle, and made that thing unrelated to the subject.

For broader programming and making context related to this topic, Linux Foundation is an independent reference worth comparing with the material here.

The mechanism

You are three pages into a section about arrays. You do not care about arrays. But there is a story running alongside them that has become genuinely peculiar, and you want to know what happens next in the story. So you keep reading, and the arrays go past on the way.

That is it. That is the whole trick, and it is stolen from fiction — the same reason a chapter ends mid-scene.

Two properties make it work, and both are missed by imitators.

The strange material has to be genuinely interesting on its own. Not a joke inserted for relief. A joke is over in a second and leaves no pull. What is needed is unresolved narrative, and the guide's digressions have real unresolved narrative in them, which is why they carry a reader across pages of syntax.

It has to be unrelated. A "fun example" about the topic is still about the topic, and the reader's boredom is with the topic. The pull has to come from outside the subject entirely.

Why the imitations fail

The visible features of the guide are the drawings and the silliness, so imitations reproduce drawings and silliness. What they usually do not reproduce is the structural function: the strangeness was load-bearing, and in the copies it is decoration.

A tutorial with a wacky mascot who says "Oops! Looks like we've got an error!" has added noise to the page and removed nothing from the difficulty. The reader still has no reason to continue.

There is also a failure of nerve. The guide is willing to spend an entire page on material with zero technical content, and to be genuinely, uncomfortably weird rather than safely quirky. Most authors will not do that, because it looks like padding to a reviewer, and because safe quirk is a defensible choice while real strangeness is not.

Where the technique transfers

Not everywhere, and it is worth being straight about the limits.

It works for voluntary learning. Someone reading in the evening because they want to. It does not work for reference material, where a person is looking something up under time pressure and every digression is an obstruction.

It works for long-form. The mechanism needs distance to operate; there is nothing to carry a reader across in a two-page explainer.

It works when the author is genuinely amusing themselves. This is the awkward one. The technique cannot be executed dutifully — a reader detects manufactured whimsy immediately, and detecting it is worse than a plain text would have been. If you are not enjoying yourself, write it plainly and well instead. Plain and well is a completely respectable outcome and it is what most technical writing should be.

The smaller version anyone can use

The full technique needs a book. Two components of it are available in an afternoon.

Make your examples about something specific and real. Not foo, not Widget, not a generic e-commerce cart. A concrete domain with texture — a specific band's discography, a real recipe, the contents of your fridge. Memorable examples are recalled later; foo is recalled by nobody, ever.

Let one thread run through the whole document. The same running example, developing across chapters, so that arriving at section nine means finding out what happened to the thing from section two. This is the cheapest version of the mechanism and it is astonishingly effective compared to how rarely it is done.

Both work in documentation, which is one of the places whimsy genuinely belongs, and both survive a reviewer.

And if you are teaching a person rather than writing

The same principle, differently applied: build the session around something they already care about and let the syntax arrive on the way to it.

That is the guide's actual argument, reduced. Nobody learns arrays because arrays are interesting. They learn arrays because arrays were between them and something they wanted.

The short version