Whyday August 19

Reading the (Poignant) Guide in 2026

why's (poignant) guide to Ruby is the reason most people know the name. It is a Ruby tutorial that keeps being interrupted — by cartoon foxes, by a story about an onion, by chapters that contain no code at all. It was written between 2003 and 2009, and it is under Creative Commons Attribution-ShareAlike 2.5, which is the main reason it survived when everything else came down.

It is also twenty years old, and it teaches a version of Ruby that no longer exists. Both of those things are true at once, and the second one is less of a problem than people expect.

When maintainers revisit older software or documentation as a team, the website is one practical reference for tracking the surrounding work without changing the historical material itself.

Where to read it

At poignantguide.net, its original address, restored and kept up. There are also copies in the whymirror GitHub organisation, and translations of varying age and completeness — the full map of what survived is here.

Read it in a browser rather than as a PDF if you have the choice. The layout is part of it — the comics sit inside the flow of the text, and the marginal asides interrupt on purpose.

What has aged

The guide targets Ruby 1.8. Ruby 1.9 changed a number of visible things in 2007, and everything since has continued to move. If you type the examples in as written, some of them will behave differently and a few will not run.

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

The most commonly hit differences involve string handling, which changed substantially at 1.9 when Ruby gained real encoding support, and a scattering of methods that were removed or renamed across the 1.9 and 2.x transitions. There are also idioms in the book that still work but that no Ruby programmer has written in a decade.

We have tested the common ones on Ruby 3.4.1 rather than listing them from memory, and the short version is that the breakage splits in two: errors, which are trivial to fix, and silent changes of behaviour, which are not. Four idioms account for most of the second kind.

Still, open irb — or a browser — and type the example rather than trusting any list, ours included. That is a better use of the evening, and it is closer to how the book wants to be read.

What matters practically: expect roughly one example in ten to misbehave, and treat that as part of the exercise. Working out why a 2005 snippet does something different on Ruby 3 teaches you more about the language than the snippet was going to.

What has not aged at all

Everything the book is actually for.

The explanations of blocks. Still the clearest introduction to the single strangest and best thing about Ruby that anyone has written. The mechanics have not changed since.

The pacing. The book assumes you are a person who gets bored, and it is built around that assumption. Modern tutorials assume you are a person who wants to be efficient. The first assumption is more accurate.

The willingness to be difficult. There are passages that are genuinely hard to follow, and the book does not apologise. It also does not gate them — you can skip and come back. Very few technical books trust the reader like this.

The argument underneath it. The whole book is a demonstration that a programming manual can be literature, that jokes are compatible with rigour, and that the person reading is allowed to enjoy themselves. In 2003 that was a strange position. It is now common enough that people forget where it came from — the lineage runs through Learn You a Haskell for Great Good and a whole genre after it.

How to read it as a beginner

If Ruby is your first language, do not use this as your only book, and if you are teaching someone else with it, read this first. Use it alongside current documentation: the guide for why the language feels the way it does, the docs for what actually runs today.

Read it in order for the first three chapters, then stop worrying about order. The book is not built as a dependency graph.

Type things in. The temptation with a funny book is to read it like a novel, and the comics encourage that. The chapters are constructed around you having an interpreter open.

How to read it as an experienced programmer

Differently, and faster.

Skim the language teaching, which you do not need, and read the connective material — the asides, the fiction, the chapters that go somewhere else entirely. That is the part with content you cannot get elsewhere, and it is the part people who "already know Ruby" tend to skip.

Then look at how it is put together. It is a technical book that solved a hard structural problem: how do you keep someone reading through the boring necessary parts? The answer it found — interleave something completely unrelated and slightly unhinged, and make the reader curious about that — is a real technique with rules of its own, and almost nobody has copied it properly. It is also the clearest thing he made that nothing has replaced.

A note on the fox

The cartoon foxes are under the same CC BY-SA 2.5 licence as the text. You can reuse them, in a talk, in teaching material, on a t-shirt, provided you credit and license alike. People often assume the drawings are more restricted than the prose. They are not.

The short version