Dave Thomas (pragdave) is soliciting feedback for a second edition of Programming Ruby (aka the "PickAxe"). Here's what he's saying on the ruby-talk mailing list:
So, this is what I'm thinking. Rather than document all the methods in all the lib/ and ext/ classes and modules, I'd like to have a one-page summary for each. Each page would contain a synopsis of the function of the library, along with a small number of samples of use. The idea is that you can read through this to find libraries that would be useful, and then consult the RDoc for details. Think of it as a kind of exhaustive library cookbook. I've posted sample pages at
http://www.pragmaticprogrammer.com/extracts/sl.pdf
(These are rough, and contain typesetting problems and other errors---I just wanted to give folks a feel for what I was talking about).
So, here's the question: is this the way to go? Are folks happy seeing this kind of synoptic information in the book, and then referring to the online or local documentation for the details? (Don't worry about the built-in stuff: I'm keeping the existing format for all of that, so you'll still have the complete method listing for String, Array, and friends).
The full message (and thread) is available here.
Update: Apparently the ruby-talk archive code is a bit behind; the link is correct, but the message isn't archived yet. At the moment, there's nothing on the ruby-talk archive page dated past March 19th.