content/posts/2004-03-23-pickaxe-ii-feedback.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

---
date: "2004-03-23T14:11:00Z"
title: PickAxe II Feedback
---

<p>
<a href='http://www.pragdave.com/'>Dave Thomas (pragdave)</a> is
soliciting feedback for a second edition of <a
href='http://www.rubycentral.com/book/'>Programming Ruby</a> (<abbr
title='also known as'>aka</abbr> the "PickAxe").  Here's what he's
saying on the <a href='http://www.ruby-talk.org/'>ruby-talk</a> mailing
list:
 </p>

<blockquote cite='http://www.ruby-talk.org/95560'>
<p>
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

<p>   
&nbsp;&nbsp;&nbsp;<a href='http://www.pragmaticprogrammer.com/extracts/sl.pdf                     '>http://www.pragmaticprogrammer.com/extracts/sl.pdf                          </a> 
</p>

<p>
(These are rough, and contain typesetting problems and other errors---I         
just wanted to give folks a feel for what I was talking about).                 
</p>
    
<p>                                                                            
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).                                                                       
</p>
</blockquote>

<p>
The full message (and thread) is available <a
href='http://www.ruby-talk.org/95560'>here</a>.
</p>

<p>
<b>Update:</b> Apparently the <a
href='http://www.ruby-talk.org/'>ruby-talk</a> 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 <a
href='http://www.ruby-talk.org/'>ruby-talk</a> archive page dated past
March 19th.
</p>