From: Sam Roberts <sroberts@...>
Date: 2004-03-23T03:08:51+09:00
Subject: Re: Need some advice on PickAxe II

I think the original Pickaxe library section was so useful mostly
because the ruby docs were so absolutely lacking. Given good online docs
in html and ri, I don't think I'd want the pickaxe2 to redocument these.

Aside: a nitpick, the organization, alphabetical within 5 chapters, is
maddening. Its the only thing about the book I consistently find
irritating. I have to guess what kind of thing a class is (Date is one
section, Time in another...), then find that chapter, then I can use the
alphabet... I can see why you wanted to do this, but for me at least, it
didn't work.

What would make me happy, is if you removed the entire library section
(especially things like, in your example sl.pdf, you document base64.rb,
but thats a fairly useless set of two single line wrappers around
pack/unpack that should never have been in the global namespace, why
spend a whole page on it?).

In its place, if you put a chapter on racc, on rexml, on webrick, on
soap4r, etc., tutorial style stuff on how to do useful things, that's
the kind of thing that I don't know will get done in the std lib
documentation, and I would be happy to buy and be able to read on my
couch, whereas it looks like the doc team (yeah team!) are doing good
work in getting the per-API docs in better shape.


Things I would like to see better docs for, at higher than API level:

- c extensions
- swig
- the ruby OO model, especially with a little more reference to java and
	C++'s
- advice on usage, when to freeze things, how to build apis, whether to
	check your arguments types, or just use duck-typing and let things
	unfold as they will

I'm a huge fan of printed docs, generally, but at some point, the std
library API becomes so huge that you get injured lifting the book, and
ruby is getting that direction.

That my 2 bits.

Thanks for the great book, v1,
Sam


Wrote Dave Thomas <dave@pragprog.com>, on Tue, Mar 23, 2004 at 02:46:42AM +0900:
> Folks:
> 
> It's looking as if we're moving towards agreement with Addison Wesley 
> on getting the rights to Programming Ruby back. This means that we'll 
> be able to produce an updated version, covering Ruby 1.8. No promises: 
> we still don't have all the signed agreements, but AW is certainly 
> being very helpful so far.
> 
> Now... I have a question. When it came to documenting the library that 
> comes with Ruby (the stuff in lib/ and ext/), the original PickAxe 
> trying to document every method in a subset of the 1.6 distribution: we 
> picked the library classes and modules that looked as if they were 
> being used.
> 
> In Ruby 1.8, the library has grown astonishingly: I count almost 100 
> library modules and classes in lib/ alone. If we were to document these 
> in any kind of detail, the book would grow to 2000 pages, and we 
> wouldn't be done until 2008 :)
> 
> At the same time, the ruby-doc folks are making significant inroads in 
> adding documentation the library itself: this is available both through 
> ri and as HTML (at ruby-doc.org, for example).
> 
> 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).
> 
> 
> Cheers
> 
> Dave
> 
> 

-- 
Sam Roberts <sroberts@certicom.com>