---
### Author:  [@Jim\_Menard3](https://rubytalk.org/u/Jim_Menard3)
#### Post date: [22 March 2004 18:19 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/3 "2004-03-22T18:19:36Z")
Dave Thomas [dave@pragprog.com](mailto:dave@pragprog.com) writes:
> 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 PDF looks great. I like the “cookbook” summary. That, paired with the new
RDocs, will be a great combination.
I’m glad you’re keeping the core classes (String, Array, and friends). The
HTML version of the built-in classes page from version 1 stays on my Bookmarks
Bar and is heavily referenced.
If you decide to release version 2 of the Pickaxe book electronically, it
would be wonderful to be able to provide links between it and the RDoc
documentation. When I’m looking at the new cookbook, I imagine my next stop
would be the RDocs to get the dirty details. I’m not sure how that would be
possible, though. The book couldn’t link to my local copy of the RDocs, of
course: that can live different places on different systems. Perhaps the
electronic version of the book could come with a snapshot of the RDocs.
Jim
> **···**
>
> –
> Jim Menard, [jimm@io.com](mailto:jimm@io.com), [http://www.io.com/~jimm/](http://www.io.com/~jimm/)
> “Mind you, deep in the IBM VM operating system source we once found a
> comment that said ‘remember to collect laundry on way home’.”
> – Alan J. Flavell in comp.lang.perl.misc
---
### Author:  [@Aredridel1](https://rubytalk.org/u/Aredridel1)
#### Post date: [22 March 2004 18:39 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/4 "2004-03-22T18:39:42Z")
> 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).
I really like it. It’s something that the ruby community lacks: a single
place to look for fairly authoratative examples of all this. The stdlib
docs don’t include enough, often (it’s improving!), so … I’m
impressed.
Ari
---
### Author:  [@Charles\_Comstock](https://rubytalk.org/u/Charles_Comstock)
#### Post date: [22 March 2004 19:14 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/5 "2004-03-22T19:14:30Z")
Dave Thomas wrote:
> 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](http://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](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
I think this is an excellent idea, what the community is particularly
lacking in terms of documentation is examples and usage. API info is
important, particularly if it’s an obscure section, but when I look at a
new library I want to know what it’s capable of, and that’s what
examples show.
Charles Comstock
---
### Author:  [@James\_Britt6](https://rubytalk.org/u/James_Britt6)
#### Post date: [22 March 2004 21:16 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/6 "2004-03-22T21:16:39Z")
Dave Thomas wrote:
> So, here’s the question: is this the way to go?
Yes.
> 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).
Yes. The book can’t cover everything, but people need to know what else
there is to know. The number of online resources is growing, so it’s
fair to refer readers to other, freely available, documents.
If somebody takes an interest in Ruby, they will likely _have_ an
installation, so they’ll have ri and the rdoc and the means to generate
the HTML files, etc. What they won’t have is any idea of all that’s in
there, so the book can serve as a road map for the more arcane features.
James
---
### Author:  [@Gavin\_Sinclair](https://rubytalk.org/u/Gavin_Sinclair)
#### Post date: [22 March 2004 21:48 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/7 "2004-03-22T21:48:13Z")
That’s a sensible approach, but I think you should be flexible about
how much detail each library gets.
For instance, ‘date’ is an important class, and a reader of Pickaxe
should come away fairly expert in its usage. ‘soap’, on the other
hand, is much more “optional”.
The differences between ‘date’ and ‘soap’ are:
- everyone needs ‘date’ from time to time, but only a few need ‘soap’;
- someone interested in SOAP (in general) should read a book on SOAP
(even though it’s not about Ruby), whereas for someone interested
in ‘date’, Pickaxe is all they’ve got.
So basically, not all libraries are equal, and they shouldn’t be
treated as such. The criteria I identified are the best I can think
of, but there may be a better way to decide what gets the one-page
treatment and what gets more detail.
Layout-wise, I’d probably do a one-pager on _all_ libraries in one
chapter, and then have a few themed chapters where some libraries are
explored in more detail.
HTH,
Gavin
> **···**
>
> On Tuesday, March 23, 2004, 4:46:42 AM, Dave wrote:
>
> > 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.
---
### Author:  [@Charles\_D\_Hixson](https://rubytalk.org/u/Charles_D_Hixson)
#### Post date: [23 March 2004 07:40 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/8 "2004-03-23T07:40:01Z")
Dave Thomas wrote:
> 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 🙂 … Cheers
>
> Dave
I am remembering how wonderful the first “Java in a Nutshell” book
was, and what a disappointment the second edition was. Be very
careful here.
I agree that you need to cover the basic classes…but better to cover
the main classes thoroughly (as a reference) and leave pointers to the
others. Don’t overkill.
My thought would be the best approach would be, after the initial
language definitions and discussions, to take a series of common
tasks, and show how to do them. A good addition would be a
cross-index of task and class, but that might be quite difficult, as
people describe the tasks so differently.
Your initial approach of building the jukebox application was an
excellent approach. Perhaps expand that into things like displaying a
graphic image that goes with the music, simple accounting of which
songs are most popular. Playing music out of the computer’s
speakers. Synthesizing the music from a score. Editing the score.
Printing the score. Etc. With lots of pointers to places on the web
where more information can be found.
P.S.: You seem to have settled on FOX as the display kit, so I don’t
know if what I was suggesting is practical. As usual, a discussion of
alternatives, and why you are choosing the direction you are choosing
is helpful.
P.P.S: Is Ruby2 in the offing? I seem to recall publishers as having
slow turn arounds…so perhaps you had better be covering that, though
whether as a “soon to appear” or as the standard version I don’t know.
---
### Author:  [@Chad\_Fowler](https://rubytalk.org/u/Chad_Fowler)
#### Post date: [23 March 2004 11:57 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/9 "2004-03-23T11:57:16Z")
Personally, I never pull out the pickaxe as a reference. I think its
real strength (and you and Andy’s core strength as a unit) is to help
people understand the high level concepts that are important when
learning a dynamic language like Ruby. To me, the biggest bang for the
buck would be for you to stay at that level, and leave API
documentation to the ruby-doc folks (which could, in this open source
community, theoretically be any/all of us).
Excellent (almost) news on the future of Pick Axe!
Chad
> **···**
>
> On Mar 22, 2004, at 12:46 PM, Dave Thomas wrote:
>
> > Folks:
> >
> > 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 🙂
---
### Author:  [@Robert](https://rubytalk.org/u/Robert)
#### Post date: [24 March 2004 07:04 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/10 "2004-03-24T07:04:29Z")
“Dave Thomas” [dave@pragprog.com](mailto:dave@pragprog.com) schrieb im Newsbeitrag
[news:DFB1150A-7C28-11D8-AA8B-000A95676A62@pragprog.com](mailto:news:DFB1150A-7C28-11D8-AA8B-000A95676A62@pragprog.com)…
> 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).
I like that approach _if_ proper online documentation is in place. This is
what happens with the cygwin install:
$ ri String
No ri documentation found in:
/usr/share/ri/1.8/system
/usr/share/ri/1.8/site
/home/Robert/.rdoc
Was rdoc run to create documentation?
I don’t say it’s your fault I just feel that there is no single and
consistent documentation standard for ruby. Although there is [ruby-doc.org](http://ruby-doc.org)
IMHO there should be a complete online reference shipped with each
installation. Or am I missing something?
And, yes, the chapter-alphabetical organization makes finding things more
difficult than it should be. That can certainly improved on.
Kind regards
```
robert
```
---
### Author:  [@Nedardstark](https://rubytalk.org/u/Nedardstark)
#### Post date: [24 March 2004 17:59 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/11 "2004-03-24T17:59:27Z")
Having one page summaries of each library seems to be a useful way to
preview, see what is of interest in order to go elsewhere to dig
deeper. I would like to see that approach taken.
Dave Thomas [dave@pragprog.com](mailto:dave@pragprog.com) wrote in message news:[DFB1150A-7C28-11D8-AA8B-000A95676A62@pragprog.com](mailto:DFB1150A-7C28-11D8-AA8B-000A95676A62@pragprog.com)…
> **···**
>
> > 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](http://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
---
### Author:  [@Piergiuliano\_Bossi](https://rubytalk.org/u/Piergiuliano_Bossi)
#### Post date: [26 March 2004 16:14 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/12 "2004-03-26T16:14:26Z")
My 2 cents (slightly related to libs): what do you think about a new
section on installation structure, explaining rationale, usage, etc of
main directories, how to install, how to shape a library in order to
install it properly and so on?
Cheers,
Giuliano
Dave Thomas wrote:
> 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.
[…]
> **···**
>
> –
> If you want to send me an email in the address you have to write ‘p’,
> then a dot, followed by ‘bossi’ at ‘quinary’, another dot and ‘com’ at last
---
### Author:  [@oinkoink](https://rubytalk.org/u/oinkoink)
#### Post date: [29 March 2004 18:49 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/13 "2004-03-29T18:49:27Z")
I loved the first Pickaxe, and I agree that with ri available,
Pickaxe II need not try to document everything. There were
two holes in the first Pickaxe that I think should be filled.
The first is that the insane gotchas that occur when you try
to do math without including mathn were not mentioned. Indeed,
I don’t think the mathn library was mentioned. Hopefully these
bugs will be fixed in Ruby by then, but if not, the book should
warn about them.
(BTW, does anybody know why these haven’t been fixed? They’ve
been known for ages, and since they are fixed by requiring mathn,
I don’t understand why mathn isn’t required automatically when
rational, complex, or matrix are.)
The second was that dealing with international character encodings
was mentioned only perfunctorily. A few examples would have been
very helpful for those of us who live in the wider, non-ASCII world.
The great thing about the Pickaxe is it really teaches you how
to think with Ruby. I had never dealt with such a dynamic, OO
language before (the closest approach having been Python), and
this book opened up a new world of programming for me.
Regards, Bret
Bret Jolly (Jou Lii Bair)
---
### Author:  [@Zachary\_P\_Landau](https://rubytalk.org/u/Zachary_P_Landau)
#### Post date: [22 March 2004 18:21 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/14 "2004-03-22T18:21:04Z")
> 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.
I’m not sure I agree with this. Programming Ruby fits very well as an
introduction (and then reference) to the language itself. I think having
in-depth examples of how to use libraries is a job for another book
(I haven’t snagged a copy yet, but it seems that Hal’s ‘The Ruby Way’
was made for this purpose). Programming Ruby should merely mention what
exists and then point the reader to the place to get more information.
> **···**
>
> –
> Zachary P. Landau [kapheine@hypa.net](mailto:kapheine@hypa.net)
> GPG: gpg --recv-key 0x24E5AD99 | [http://kapheine.hypa.net/kapheine.asc](http://kapheine.hypa.net/kapheine.asc)
---
### Author:  [@Lothar\_Scholz2](https://rubytalk.org/u/Lothar_Scholz2)
#### Post date: [22 March 2004 22:28 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/15 "2004-03-22T22:28:12Z")
Hello Charles,
Monday, March 22, 2004, 8:14:30 PM, you wrote:
> I think this is an excellent idea, what the community is particularly
> lacking in terms of documentation is examples and usage. API info is
> important, particularly if it's an obscure section, but when I look at a
> new library I want to know what it's capable of, and that's what
> examples show.
And immediately followed by shaking your head because you can't find
out what the method returns or how the error handling is done -
okay real programmers don't need error handling as long as your
computer has a reset button.
So both are very very necessary for a successful library.
But it still leaves the problem that the book would be around 2000
pages. Some publishes like to hear this. So maybe moving from AW to
Wrox Press may be a solution 🙂
> **···**
>
> --
> Best regards,
> Lothar [mailto:mailinglists@scriptolutions](mailto:mailinglists@scriptolutions).com
---
### Author:  [@Nathaniel\_Talbott1](https://rubytalk.org/u/Nathaniel_Talbott1)
#### Post date: [23 March 2004 13:31 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/16 "2004-03-23T13:31:41Z")
---
### Author:  [@Nathaniel\_Talbott1](https://rubytalk.org/u/Nathaniel_Talbott1)
#### Post date: [23 March 2004 13:41 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/17 "2004-03-23T13:41:56Z")
> > Folks:
> >
> > 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 🙂
>
> Personally, I never pull out the pickaxe as a reference. I think its
> real strength (and you and Andy’s core strength as a unit) is to help
> people understand the high level concepts that are important when
> learning a dynamic language like Ruby. To me, the biggest bang for
> the buck would be for you to stay at that level, and leave API
> documentation to the ruby-doc folks (which could, in this open source
> community, theoretically be any/all of us).
I guess I’m just the opposite… the number one thing I’ve used my
Pickaxe for is an API reference. I like having a dead tree form I can
thumb through looking for what I want, and the Pickaxe goes everywhere
with me in my backpack. The second most useful part to me has been the
language reference - when learning Ruby it seemed like I found
something new and cool about the syntax in there every other day. I
personally picked up the high level concepts of a dynamic language
mostly elsewhere, both before and after discovering Ruby. Different
strokes for different folks, I guess.
Anyhow, I like the general direction Dave’s pointing out for this
edition, because there’s a lot of good stuff in the standard library
that folks don’t even know about, but it would be overkill to
comprehensively document all of it in the same book. OTOH, I’d love it
if some of the most useful, general purpose libraries had good,
comprehensive API documentation in the style of the original Pickaxe.
Things like WEBrick, Test::Unit, DRb, optparse, etc., that mailing list
traffic show are being used on a regular basis.
Oh, and mostly unrelated: I hope this edition uses under\_score notation
instead of camelCase. I know I was led astray by the Pickaxe in my
early days of Ruby programming :-/
> Excellent (almost) news on the future of Pick Axe!
My current one is looking really abused… it’s about time to get a new
one to beat up in my backpack 🙂
Nathaniel
Terralien, Inc.
\<:((\>\<
> **···**
>
> On Mar 23, 2004, at 05:57, Chad Fowler wrote:
>
> > On Mar 22, 2004, at 12:46 PM, Dave Thomas wrote:
---
### Author:  [@Dave\_Mail\_Archive](https://rubytalk.org/u/Dave_Mail_Archive)
#### Post date: [23 March 2004 14:01 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/18 "2004-03-23T14:01:19Z")
> My thought would be the best approach would be, after the initial
> language definitions and discussions, to take a series of common
> tasks, and show how to do them. A good addition would be a
> cross-index of task and class, but that might be quite difficult, as
> people describe the tasks so differently.
I see that as the role of books such as The Ruby Way and the Developers
Guide. The Pickaxe is really intended to be a guide to Ruby, The
Language. We mention other major libraries briefly, but not in the kind
of depth that other go into. Again, it’s a question of space and
pagecount.
> P.S.: You seem to have settled on FOX as the display kit, so I don’t
> know if what I was suggesting is practical. As usual, a discussion of
> alternatives, and why you are choosing the direction you are choosing
> is helpful.
I’m not sure where that impression came from: as it stands right now
I’ve actually removed the Tk chapter from the book. The Ruby GUI
picture is frankly something os a mess, and I didn’t want to go there.
I’d welcome advice here.
> P.P.S: Is Ruby2 in the offing? I seem to recall publishers as having
> slow turn arounds…so perhaps you had better be covering that, though
> whether as a “soon to appear” or as the standard version I don’t know.
The publisher we’re using has the fastest turnaround in the industry…
🙂
Cheers
Dave
The Pragmatic Bookshelf
> **···**
>
> On Mar 23, 2004, at 1:40, Charles Hixson wrote:
---
### Author:  [@Dave\_Mail\_Archive](https://rubytalk.org/u/Dave_Mail_Archive)
#### Post date: [24 March 2004 15:53 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/19 "2004-03-24T15:53:06Z")
> I like that approach _if_ proper online documentation is in place.
> This is
> what happens with the cygwin install:
Could you perhaps contact whoever is responsible for that install and
ask them to check out the RDoc stuff: it _should_ be included.
> And, yes, the chapter-alphabetical organization makes finding things
> more
> difficult than it should be. That can certainly improved on.
And it will be 🙂
Cheers
Dave
> **···**
>
> On Mar 24, 2004, at 1:04, Robert Klemme wrote:
---
### Author:  [@James\_Britt6](https://rubytalk.org/u/James_Britt6)
#### Post date: [24 March 2004 16:05 UTC](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692/20 "2004-03-24T16:05:18Z")
Robert Klemme wrote:
> Was rdoc run to create documentation?
Did you run rdoc?
> I don’t say it’s your fault I just feel that there is no single and
> consistent documentation standard for ruby. Although there is [ruby-doc.org](http://ruby-doc.org)
> IMHO there should be a complete online reference shipped with each
> installation. Or am I missing something?
You should, at some point, be able to run rdoc on the full source code
and get the same API docs as you would find on [ruby-doc.org](http://ruby-doc.org) (modulo
recent updates to the latest CVS)
I believe there have been discussions (on ruby-core?) on whether this
should happen by default as part of the installation process, or if it
should be a deliberately chosen option (something like --with-rdoc or
whatever).
I’d argue for installing docs by default.
James
[Next page](https://rubytalk.org/t/need-some-advice-on-pickaxe-ii/10692.md?page=2)