poignant-guide rescues a Ruby book that its author took off the web

A book that was taken off the internet in 2009

The Poignant Guide to Ruby is a book written by Why the Lucky Stiff, and the reason this repository exists is that the author removed it from the web.

On August 19, 2009 Why the Lucky Stiff removed every trace of his work from the Web, including this book. The maintainer of this repository salvaged it from the Internet archive and re-published it, and the book is now served from the project's own domain.

That origin explains the shape of the repository better than any feature list could. This is not a tutorial project in the sense of a maintained guide to a current language. It is a rescue of a specific artefact, with a specific author's voice, from a specific moment in Ruby history, republished by someone who cared enough to keep it available.

The original work was under the Attribution-ShareAlike licence, and the README links the Creative Commons terms. That single fact governs most of what a reader, a teacher or a publisher can legitimately do with the text, and it is worth reading before you copy a chapter.

The repository also carries the trappings of the original book rather than of a software project. Alongside the chapters and the site build there are directories named book, dwemthy, soundtrack, script and images, plus a stylesheet called guide.css and a CNAME file that points the domain at the site. Those are the remains of a book that shipped with music and an interactive piece.

What follows is an account of what was changed, what was left broken, and what it means for anyone reading Ruby today.

Seven changes that make the code run again

The README lists what the maintainer did to the salvaged text, and the list is short enough to quote in full because each item is a concrete editorial decision.

The code examples were changed so they never generate syntax warnings, and they were updated to match Ruby 1.9 behaviour. Grammar and spelling corrections were applied. Outdated Ruby installation instructions were updated.

Then the structural changes. The HTML book was converted into Markdown, noting that Why the Lucky Stiff originally authored it in Textile. A build system powered by Jekyll was added. Syntax highlighted code was enabled where previously there was none.

Two of those deserve a note. The Textile to Markdown conversion is the reason the repository now holds _posts directories and Jekyll layouts rather than a set of static HTML pages, and it is also the change with the widest consequences for reuse, since a book authored in Textile is difficult to reuse in other publishing systems and one authored in Markdown is not.

The Ruby 1.9 update is the change that makes the code examples still runnable at all, and it also dates the work precisely. Ruby 1.9 was a transitional release whose changes to hash syntax and string encoding were widely disliked on arrival and are now simply how Ruby looks. A book that has been brought up to 1.9 but not further tells you exactly where its maintainer drew the line.

Syntax highlighting is the one addition that has nothing to do with correctness and everything to do with reading. It is the difference between a code listing you can skim and one you cannot.

The book is a Jekyll site, and the chapters live in _posts

The build system is Jekyll, and the README gives one command:

jekyll serve

That builds the site locally, and the README links to the GitHub Pages guide on using Jekyll with Pages for the details of hosting.

The individual chapters are in the _posts directory. That is the Jekyll convention for content that is dated, and it is the reason the book reads as a sequence of posts rather than a table of contents with numbered pages.

The rest of the layout follows standard Jekyll practice. There is a Gemfile and a Gemfile.lock, so the Ruby version and the plugin set are pinned, a _config.yml for site configuration, and the usual _layouts and _includes directories for the page templates. The root also has index.html, 404.html and the guide.css stylesheet, plus an images directory for the illustrations that accompany the chapters.

Nothing in this part of the repository is unusual, and that is the point. Rebuilding the book on a static site generator is what makes it survive: the original was a set of pages on the web that its author could and did remove, and the republished version is a repository that anyone can fork, build and host.

For a reader, the practical consequence is that the site can be served locally, which is how you would read it if you want to read the whole thing in order rather than jumping between pages online.

A missing chapter and a translation of unknown age

Two gaps in the book are documented, and both are worth knowing about before you rely on it as a complete text.

The first is a missing chapter. Chapter 8, Heaven's Harp, was never recovered. The README speculates that Why the Lucky Stiff started drawing it and never finished or published it. So the book you are reading has a hole in it, and no amount of building will fill it, because the source does not exist.

The second is a translation. The README links a Japanese translation of the book and says plainly that the author cannot tell how up to date it is. That is an unusual admission to leave in the documentation, and it is the right one: a translation of a 2009 book that may or may not reflect the current Markdown and Ruby 1.9 corrections is a different document from the English text in this repository.

A third fact belongs here as well, because it explains the character of the material. The README quotes a passage from the book as an epigraph, a piece of writing about a shoe in a car and a note from a deceased ancestor. The book was written by a musician and artist as much as by a programmer, and the quotations, the illustrations, the soundtrack directory and the dwemthy directory are all evidence that the original was a multi-part work rather than a conventional manual.

That is a real strength for a reader and a real problem for a reference. Nothing in it was written to be a specification, and it should not be read as one.

Where this guide is the wrong tool

The limitations are not subtle, and they follow from what the project is.

It is not a current Ruby reference. The code examples were brought up to Ruby 1.9 behaviour and no further, which means constructs introduced after that release are absent and idioms that have since shifted are presented as they were in the late 2000s. A developer learning Ruby in 2026 needs a different text, and this one will mislead in places for exactly the reason that it is charming.

It is not structured for lookup. A book organised as prose chapters with a voice is a poor tool for answering a specific question about a method signature, and the site has no search described in the README.

It is not a testable or verifiable artefact either. There is no test suite, no linting configuration and no continuous integration in the repository, so there is no way to know whether the code examples still run. The claim that they no longer generate syntax warnings is the maintainer's statement, and it is a statement about the state of the book at the time it was made.

The reuse question is the one most people hit first. The text is under Attribution-ShareAlike, so you may share and adapt it provided you attribute it and license your adaptation under the same terms. That is workable for a course, a translation or a derivative book as long as you are prepared to release the derivative under the same licence. It is not workable if you need to fold chapters into a commercially licensed textbook.

And the practical risk is simple: the repository has no releases, so there is no version to pin, and the domain is the canonical copy.

A rescue that is still being maintained, on a repository with no releases

The maintenance state is mixed and worth stating precisely.

The repository is not archived and the last push was on 2026-04-20, so the site and the book are still being looked after, roughly six months before now. There are no GitHub releases, which for a static book site is unsurprising, and it means there is no versioned artefact to pin if you fork it.

The licence needs two sentences rather than one. The repository itself does not name a licence in a way that a reader can rely on, while the README states that the original work was under the Attribution-ShareAlike licence and links the Creative Commons terms at version 2.5. For a text repository, that second statement is the operative one: the book carries share-alike terms because that is how it was licensed when it was written, and the person who rescued it republished it under those terms rather than relicensing it.

What this means practically is that a reader can rely on the site being there and being updated, and cannot rely on the repository offering a stable version history. The chapters are the source of truth, and they are edited in place.

For a reader, the answer is simple: read it at the site, treat it as a historical document with an unusually good editor, and check the share-alike terms before you put any of it into something you publish. For a maintainer, the interesting question is what the rescue still needs, which the README answers only by omission, since there is no contributing guide and no issue tracker mentioned in the pages we have.

Editorial conclusion

Ruby developers who want the original Poignant Guide to Ruby in a readable, searchable form should read the version at poignant.guide, because the repository fixed the parts that had decayed, moved the book from Textile to Markdown and gave it a working Jekyll build. It is the wrong reference for modern Ruby work, since the code targets Ruby 1.9 behaviour and the book itself predates most of the language, and it is the wrong source if you need material you can republish freely, because the text is under an Attribution-ShareAlike licence. Before reusing any chapter in your own course or book, check the share-alike terms and whether the missing chapter eight, Heaven's Harp, matters to you, because it was never recovered.

Frequently asked questions

Official sources

1. Issues
2. mislav/poignant-guide on GitHub
3. Project website
4. README