Poignant documentation
I'm still not awake enough to post a more substantive entry, but as I was on my way to bed I remembered that I'd been meaning to re-post this, from an email I wrote a while back:
A friend of mine once came up with a programming language that allowed the programmer to express emotion--I think it was called "!" (pronounced "Bang!", of course).
This isn't quite the same thing, but it reminded me of that: someone whose name is apparently "Why" (or perhaps "why the lucky stiff") has written an online book about a programming language called Ruby. The book is titled Why's (Poignant) Guide to Ruby.
Excerpt:
I'll be straight with you. I want you to cry. To weep. To whimper sweetly. This book is a poignant guide to Ruby. That means code so beautiful that tears are shed. That means gallant tales and somber truths that have you waking up the next morning in the arms of this book. Hugging it tightly to you all the day long. If necessary, fashion a makeshift hip holster for Why's (Poignant) Guide to Ruby, so you can always have this book's tender companionship.
And a bit later, in a section titled "How Books Start":
Now, if you ever have read a book, you know that no book can properly start without an exorbitant amount of synergy. Yes, synergy. Maybe you didn't know this. Synergy means that you and I are supposed to cooperate to make this a great reading experience.
We start off the book by getting along well in the Introduction. This togetherness, this synergy, propels us through the book, with me guiding you on your way. You give me a reassuring nod or snicker to indicate your progress.
That section goes on to talk about cartoon foxes.
The author is entertaining and engaging and a bit loony (in the nicest sense of the term). The book reads to me kind of like the Perl books, only a little sillier and somehow a little more heartfelt-sounding. Not many programming books have made me laugh; this one made me laugh several times in the first two pages.
Be sure to check out the sidebars on the right sides of the book's pages. I think more documentation could use silly right-hand sidebars that talk about turning the documentation into a movie starring Alec Baldwin.
