Suggestions to the Ruby community

ruby-talk
41

In my original post i thought i made it clear that i am referring to the
overall online english documentation for modules/methods and ruby in
general (since that is what i specifically stated in my original
post).

Specifically stating something general?

So again, could you give us some specific examples of actual
I feel that in my original post i was specific as i could be.

You’ll have to be more specific for people to understand what you’re
talking about, let alone agree.

Massimiliano

···

On Sat, Aug 31, 2002 at 06:55:55AM +0900, stibbs wrote:

42

You have a pet Triceratops ?! COOL !

SCNR,

-Martin

···

On Sun, Sep 01, 2002 at 11:20:51AM +0900, Matt Gushee wrote:

[…]
Wikis are cool, but as the primary form of Ruby documentation? Please, no!

Wikis appeal to the geek world, and a subset of it at that. I believe
the original poster’s main argument was that Ruby needs better
documentation to be accepted by businesses. You show me a suit who can
get his head around a Wiki, and I’ll show you my pet Triceratops.

43

I believe even a suit can get his head aroun www.emacswiki.org. So
get your Triceratops ready. :slight_smile:

That said, I too agree that using a wiki as a primary mean would be
pushing things a bit too much. But for cookbook style documentation,
I find the above mentioned site pretty much shows it can be done and
it can be done well.

Massimiliano

···

On Sun, Sep 01, 2002 at 11:20:51AM +0900, Matt Gushee wrote:

On Sun, Sep 01, 2002 at 10:37:52AM +0900, yct wrote:

instead of everyone writing your own documentation, wouldnt a wiki
documentation better? everyone could just ‘fix’ what is wrong, add
exemples. japanese documentation could just be put there and then
somebody else who knows japanese and english could translate it later.

just a wierd idea.

I agree with the closing sentence :wink: Wikis are cool, but as the primary
form of Ruby documentation? Please, no!

Wikis appeal to the geek world, and a subset of it at that. I believe
the original poster’s main argument was that Ruby needs better
documentation to be accepted by businesses. You show me a suit who can
get his head around a Wiki, and I’ll show you my pet Triceratops.

44

Indeed. I was looking at my offline backup. :frowning: It was contained in the
Windows Installer RubyHelp doco, too.

Quel fou suis-je. :wink:

Gavin

···

----- Original Message -----
From: “ts” decoux@moulon.inra.fr
To: “ruby-talk ML” ruby-talk@ruby-lang.org
Cc: ruby-talk@ruby-lang.org
Sent: Sunday, September 01, 2002 10:47 PM
Subject: Re: suggestions to the Ruby community

From: “Jim Freeze” jim@freeze.org

On Sun, Sep 01, 2002 at 08:36:54PM +0900, Gavin Sinclair wrote:

So I’m reading tempfile.rb!

Try the online pick-axe book.

That’s exactly where I couldn’t find it!

Well, there is a problem

http://www.rubycentral.com/book/lib_standard.html#Tempfile.new

Guy Decoux

45

But no Lysenkoism… :slight_smile:

Heh heh… my neck is getting longer from
staring at this screen.

Hal

···

----- Original Message -----
From: “Gavin Sinclair” gsinclair@soyabean.com.au
To: “ruby-talk ML” ruby-talk@ruby-lang.org
Sent: Wednesday, September 04, 2002 10:52 AM
Subject: Re: suggestions to the Ruby community

----- Original Message -----
From: " JamesBritt" james@jamesbritt.com

Can’t we have a bit of Lamarckianism?

Yes! Yes! Some Lamarckianism please! :slight_smile:

Gavin

46

And there’s always a danger of the embedded documentation getting out of
sync with the code.

On the other hand, I’m not sure that ‘let coders code, and writers
write’ is always a good solution either. If you have sufficient
resources to support separate people writing code and documentation,
and the organizational culture is such that developers and writers can
adequately communicate, that division of labor can produce good results.
Yet there’s an awful lot of bad software documentation out there, and a
good portion of it is written by professional writers who seem to have a
poor understanding of the product they’re writing about. And there are
many situations (e.g. sole contractor gigs and small-to-medium open
source projects) where there simply isn’t a tech writer available.

And the idea that programmers can’t write is a stereotype. I know
at least half a dozen programmers who are excellent writers. Writing
inspiring prose may be a rare gift, but any intelligent adult should
be capable of writing clear descriptions and instructions if they set
their mind to it. With sufficient peer pressure, more people might do
just that.

As for the problem of things being ‘obvious’, the solution to that is
feedback. Bugs in the documentation? Submit a bug report.

···

On Thu, Sep 05, 2002 at 04:25:10AM +0900, bbense+comp.lang.ruby.Sep.04.02@telemark.stanford.edu wrote:

    • For it’s stage Ruby has some pretty amazing online
      documentation, but it has no real documenters. It has book
      authors ( which is a very good thing), but nobody committed to
      the dirty thankless task of documentation management.

Why isn’t documentation considered part of coding? If you write some code
you are (or should be), by definition, its documenter.

    • In practice this almost never works. Writing good code and
      writing good documentation are separate skills. Even if you
      can write documentation as the code’s author, you often have
      many things that are “just obvious” that you never even think
      to document.

–
Matt Gushee
Englewood, Colorado, USA
mgushee@havenrock.com

47

It’s a mildly depressing fact of life that this is the case in any
arena where pubic discussion is easy. Lots of talk, little doing.

The best course of action is generally to pay some attention to all
the conversation, but not too much attention to the conversation
involving people not actually doing anything. Saves much hassle and
aggrivation.

···

At 4:25 AM +0900 9/5/02, bbense+comp.lang.ruby.Sep.04.02@telemark.stanford.edu wrote:

I’m just trying to introduce a bit of scale
into the problem. As I see it, there are a lot of people
complaining and very few doing.

–
Dan

--------------------------------------“it’s like this”-------------------
Dan Sugalski even samurai
dan@sidhe.org have teddy bears and even
teddy bears get drunk

48

The Unix example seems to have worked. There were special circumstances:

@ Participants at the beginning were excellent authors as wsel as
cevelopers
@ Purpose of system was to be a platform for the original team to work
on but they sere also creating a development environment for others.
@ Someone was the boss and could dictate a standard.

But the ruby world has parallel circumstances:
@ We have many excellent authors in our community-
+ Programming Ruby, for example, is destined to be a classic
of the level of Programming in the Unix Environment
+ The quality of writing on ruby-talk is far above the writing
on most other lists. One reason that this list is so genteel is that
people on the list can express themselves without offense. The recent
thread , “Suggestions to the Ruby community”, is a world class example
of a very provocative statement being metabolized through reasoned
discussion to a constructive community growth experience.
@ We all understand that the success of ruby depends on how much use
is made of it.
@ Matz has “special authority” earned by his whole person.

One new possibility is wiki.

I suggest people decide on a man style format. Even if it is not
compleltely standard from the start it will evolve. Finally, all
documentation be put on a wiki with version control. Anybody can modify
or annotate the docs and after some time a people wishing to earn a
reputation as a writer can review the history of documentation changes
and evolve the documentaton to the next level.

Sorry to be so long winded. But in addition to my technical interest I
am fascinated by the diversity and collaborative spirit of the ruby
community. Ruby and other open source communities going back to the
Unix team at Bell Labs are the best answer to 9/11.

John

It may have been that a group of good writers happeened to be also the
coders and that they were creating a system for others as well as
themselves to work on.

49

Those who can do,
those who cant teach (or critisise - much of a muchness)

And those who can do neither administrate.

This is the point I think the original poster was trying to make.
Perhaps he and his colleagues can do “ri” and “google” (and even get a
usable English copy from the Japanese) but the higher-ups who pay their
salaries do not consider such puruits “productive”. And these guys know
it!

So, the “easy” short-term solution is to -not- adopt Ruby when the check
writers are content with the status quo, whatever that may be. The suits
won’t show any interest unless and until Ruby is “buzzy”.

Of course, for that to happen, those who -do- the work must elect Ruby
over the alternatives. Perl was elected over C for sysadmin and CGI
because it made the programmers’ lives easier; no “suit” decreed the use
of perl.

In the days when C was fairly well-documented but still “involved” in
terms of getting from a to b while perl was poorly documented but
relatively sleek in the same terms, programmers turned increasingly to
perl for day to day solutions.Today is somewhat different: perl -is-
fairly well-documented and the on-the-surface differences between perl
and Ruby are not that great, thus the hurdles to overcome when
advocating a switch become, paradoxically, greater.

As Larry Wall astutely observed, programmers are by nature lazy; if it
is easier to stay with the tools they have, that is what they will do.
If a dearthe of documentation is -perceived- as a disadvantage to Ruby,
many working programmers will not switch. Regardless of whether a
perception is accurate or not, the resulting reality (that is, the
action taken) is the same.

stibbs has pointed out what he believes to be a widespread perception
that may be holding back the adoption of Ruby; to that extent, IMO it is
an issue the community should address, whether in fact it is or not an
issue within the community.

Regards,

Kent Starr

···

On Fri, 2002-08-30 at 09:35, Peter Hickman wrote:

At one school I attended I wasn’t allowed to do technical drawing
because I failed Latin!

50

From: bbense+comp.lang.ruby.Sep.04.02@telemark.stanford.edu
[mailto:bbense+comp.lang.ruby.Sep.04.02@telemark.stanford.edu]
Sent: Wednesday, September 04, 2002 12:25 PM
To: ruby-talk ML
Subject: Re: suggestions to the Ruby community

Still, hasn’t the Perl experience shown that bundling
documentation with the
code distribution is a good idea? Does every language have to go through
the same evolutionary steps? Can’t we have a bit of Lamarckianism?

    • I think it’s a good idea, particularly in a language as
      readable as Ruby. I’m just trying to introduce a bit of scale
      into the problem. As I see it, there are a lot of people
      complaining and very few doing.

I don’t see people complaining, I see people questioning, or raising
concerns, or thinking out loud, or any number of things. I don’t think you
intended to be pejorative, but it is not uncommon on this and other lists
for some people to label certain discussions as “complaining”, or
“bickering”, or “whining”, with the result of discouraging people from
speaking up. (“Complaining”, “bickering”, etc. seem to be defined as
“prolonged discussion on something one has now decided to stop
considering.”)

It is entirely possible to see a problem but not have a solution, yet some
prefer that nobody speak up unless they can propose an alternative. (And
then, when they do, they are told that they should go implement it since
they thought of it.)

OK, end of rant.

There are some discussions that, ultimately, do not have a software
solution. They deal more with the underlying principles and philosophy of
the community. They may not converge on a solution in one or two days.
Matters of documentation may fall into that category. Code runs whether you
have comments or not, so who cares, right? What constitutes “appropriate”
documentation is quite subjective. “Official” documentation standards or
not, what will ultimately drive the creation and maintenance of good, useful
documentation are community values.

It won’t just happen
overnight. Standards are nice, but usable standards require
a tremendous amount of work.

To continue your biology metaphor

 "ontogeny recapitulates phylogeny"

Every language needs to go through the stages, it’s just a
question of how fast. I think Ruby could go through this
stage fairly quickly, but I don’t expect to see a standard
document format until at least a year after raa.succ ( whatever
that turns out to be ) is well in place.

I mentioned Lamarckianism because I view the biology metaphor as deeply
suspect.
Some people seem to take it on faith that language development must follow
some Darwinian, evolutionary processes, but we are not dealing with biology.
We have the advantage of extreme hindsight, and the divine ability to
manipulate things at will. Every language need not go through the same
stages.

Conceivably, Matz could just mandate some feature that dictated the path of
Ruby documention. This is unlikley, but ultimately there needs to be an
explicit guiding hand. Relying on some sort of marketplace of competing
formats, styles, and philosophies of documentation, wherein most of the
mistakes of the past are repeated, before electing a format, seems
needlessly expensive.

There is another thread right now concerning Java and Ruby, and while I
don’t greatly care for Sun or Java, Java has a big advantage in that Sun is
quite happy to mandate certain features, such as JavaDoc. Its discouraging
to think that a standard Ruby API doc format won’t occur until a year after
some unknown time in the future.

Right now, Ruby has RD (a markup language), and RDoc (a tool for extracting
and formatting salient code features and comments). RDoc and rdtool should
be part of the base distribution. Essential documentation for the core
classes should be with the source code, and updated as the source is
updated. Docs can be generated whenever a you grab a new release. Minimal
documentation should include what the class or module is for, what each
method is for, what each method parameter is for.

We might look at the Sun’s “Requirements for Writing Java API
Specifications”
(Oracle Java Technologies | Oracle) as a
guideline.

We should ask, what’s the cost of selecting a possibly sub-optimal API
documentation standard now, versus the cost of waiting until one emerges a
year after RAA.next, while further adoption of Ruby is dampened by the lack
of complete documentation.

Exactly true. Yet there is the idea that one can just post to
ruby-talk as
a substitute for having clear documentation. Or that leafing through
multiple books is a good way to find out what some method
parameter is for.

    • Well, that works fine until you reach a certain scale of
      use. IMHO, the demand for perl-style documentation is
      getting the horse in front of the cart.

That scale of use won’t happen if people find it too hard to locate complete
class and library help. I define “too hard” as having to look in more than
one place. Many people have decided they like Ruby, and have stuck with it
long enough to figure out all the places to dig when trying to learn the
language. Others, though, have walked away because this is just too much of
an investment. For the former, the various workarounds adopted in lieu of
complete API documentation have become second nature, so that when somebody
such as stibbs suggests this is a real problem, people act puzzled.

Ruby itself wins over hackers and language fans, but persuading management
is a bit harder.
(Kent Starr expressed it quite well in [ruby-talk 49040].)

There is a chicken
and egg problem here, once consensus is reached then
most people will fall in line, but people are reluctant
to put much effort into documentation until consensus
is reached.

People don’t omit documentation because they don’t know what style to use;
they omit it because they know they will not get any flack. Many of the
Java developers I worked with never bothered to write even basic JavaDoc
comments, and it wasn’t because they were ignorant of JavaDoc. It was
because they could wave their hands and tell people “read the source”, and
people considered that acceptable geek machismo. Later, these same people
wondered why management wanted to drop the custom code and go with an
off-the-shelf, fully documented product.

Why isn’t documentation considered part of coding? If you write
some code
you are (or should be), by definition, its documenter.

    • In practice this almost never works. Writing good code and
      writing good documentation are separate skills. Even if you
      can write documentation as the code’s author, you often have
      many things that are “just obvious” that you never even think
      to document.

That someone isn’t as good at writing docs as writing code shouldn’t excuse
anyone from writing docs. Besides, “skill to do comes from doing.” I also
agree with Matt Gushee’s comments in [ruby-talk 49021]. It would be nice to
have the appropriate division of labor, but in the meantime, software
developers need to write.

    • In my experience, when you start saying “should” in the open
      source world you’re generally wasting your time. I don’t think
      you’ll get any real disagreement with the above statement, the
      problem is picking the standard.

I know, it’s sort of like saying, “Somebody should take out the garbage.”
By and large, open-source software (OSS) developers produce those things
they enjoy doing, which often overlaps with those things other people want
or need. But it’s the gaps and omissions that discredit much OSS in the
eyes of many looking for professional-grade tools. There isn’t always
somebody taking out the garbage.

But some matters seem as if they should be
fairly simple to resolve. For example, where does documentation
(in any
format) go if it’s not embedded in the code? Can we just agree
that every
lib distribution has an immediate subdirectory called ‘docs’,
and avoid the
‘lib/dbi/doc/DBI_SPEC’ problem?

    • These are not “fairly simple to resolve”, they are exceedingly
      complex and require a lot of community thrashing and
      competition between competing ideas/models before consensus
      is reached. Standards emerge from the documentation,
      documentation does not emerge from standards. I’m not saying
      we should not tackle these problems, I’m saying it’s a lot
      more complicated that most people seem to think.

Resolving every aspect of a uniform documentation process may be complex.
Where to place the docs in a library distribution is not.

James

···

-----Original Message-----
JamesBritt james@jamesbritt.com wrote:

    • Booker C. Bense
51

[…]

TROLL?
This is a copy of http://www.ruby-talk.org/48667, a message belonging
to the thread which got closer to a real flamewar since I subscribed to
this ML.

Moreover, the headers reveal the following:
X-From-Usenet: see Received: header above.
X-rubymirror: yes
X-Spam-Status: No, hits=3.3 required=5.0
tests=FORGED_RCVD_FOUND,NO_MX_FOR_FROM,RCVD_IN_ORBZ version=2.20
X-Spam-Level: ***

This looks like a forged posting to comp.lang.ruby!

···

On Mon, Dec 09, 2002 at 12:33:56AM +0900, stibbs wrote:

On Fri, 30 Aug 2002 05:23:23 -0400, Phil Tomson wrote:

In article pan.2002.07.31.02.21.23.199006.6766@nothanks.com, stibbs
stibbs@nothanks.com wrote:

On Thu, 29 Aug 2002 20:12:24 -0400, Lyle Johnson wrote:

stibbs wrote:

–
_ _

__ __ | | ___ _ __ ___ __ _ _ __
'_ \ / | __/ __| '_ _ \ / ` | ’ \
) | (| | |__ \ | | | | | (| | | | |
.__/ _,|_|/| || ||_,|| |_|
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com

Sex dumps core
(Sex is a Simple editor for X11)
– Seen on debian bugtracking

52

A suggestion for the ‘ri’ program…

A list of related items at the end of a description (like man pages). For
example, ‘ri String#downcase’ would display something like:

-------------------------------------------------------- String#downcase
str.downcase → aString

···

On August 30, 2002 08:16 pm, Phil Tomson wrote:

So I’ll try one more time: Can you give us a specific example where you
found that you needed more information or the information wasn’t clear?
For example, you could say: “The explanation of the foo method in the
module Fooable didn’t tell me anything about how instance variables of the
class it is being mixed into will be affected”.

 Returns a copy of str with all uppercase letters replaced with
 their lowercase counterparts. The operation is locale
 insensitive---only characters ``A'' to ``Z'' are affected.
    "hEllO".downcase   #=> "hello"

 See Also: String#downcase!, String#upcase, String#upcase!

IMHO that extra bit of information helps a lot in some cases. Sometimes i find
a method that does something close to what i want, so i go looking for
similar ones. Other times i know of a method that does the opposite of what i
want to do.

A --help switch would be nice too. I’m used to typing that for all my apps and
it took me a while to figure out ri with no arguments displays its help,
hehe.

–
To call me “awesome” is an understatement.

53

From: “stibbs” stibbs@nothanks.foo.web-hosting.com

So again, could you give us some specific examples of actual

I feel that in my original post i was specific as i could be.

OK, I’m not flaming you. I’m just trying to communicate.

Phil’s request is reasonable. And you have not been as
specific as you could be, because you have not named
even ONE item that needs improved documentation.

If people
here feel that the the overall online english ruby documentation does not
need improvement, great.

No one said that! There’s a huge need for improvement. But
there’s also a huge amount out there.

It’s reasonable then to point the question back at you! :wink: If there’s a huge
need for improvement, what’s an example?

OK, I myself will be specific.

Here are (some) things that I think ARE documented
adequately in English:

  1. Core classes: Array, Bignum, Binding, Class, Continuation,
    Dri, Exception, FalseClass, File, File::Stat, Fixnum, Float,
    Hash, Integer, IO, MatchData, Method, Module, NilClass,
    Numeric, Object, Proc, Range, Regexp, String, Struct,
    Struct::TMS, Symbol, Thread, ThreadGroup, Time, TrueClass

  2. Core modules: Comparable, Enumerable, Errno, FileTest,
    GC, Kernel, Marshal, Math, ObjectSpace, Process

  3. Standard libraries: Complex, Date, English, Find, Ftools,
    Getoptlong, Mkmf, Parsedate, PStore, Tempfile, Mutex,
    ConditionVariable, Timeout, WeakRef

  4. OOP libraries: Visitor, Delegation, Observer

  5. Networking Libraries: BasicSocket, IPSocket, TCPSocket,
    SOCKSSocket, TCPServer, UDPSocket, UNIXSocket, UNIXServer,
    Socket, Net::FTP, Net::HTTP, Net::HTTPResponse, Net::POP,
    Net::APOP, Net::POPMail, Net::SMTP, Net::Telnet, CGI,
    CGI::Session

  6. Other stuff: RDOC, REXML, DRb, eRuby, irb, debug.rb,
    and so on.

Which of these do you consider underdocumented? Or is it
something else entirely?

Hal

Your enumeration of the well-documented aspects of Ruby is correct, IMO. I’ve
never had any trouble getting documentation on classes and methods in the
language and its standard libraries. Well, no more trouble than having to flip
between ri, Pickaxe and Nutshell.

However, if you have a proper Perl installation on your system, take a look at
“man perl”. Apologies for the long post, but here is all the links to other
manpages it contains:

perl Perl overview (this section)
perlfaq Perl frequently asked questions
perltoc Perl documentation table of contents
perlbook Perl book information

perlsyn Perl syntax
perldata Perl data structures
perlop Perl operators and precedence
perlsub Perl subroutines
perlfunc Perl builtin functions
perlreftut Perl references short introduction
perldsc Perl data structures intro
perlrequick Perl regular expressions quick start
perlpod Perl plain old documentation
perlstyle Perl style guide
perltrap Perl traps for the unwary

perlrun Perl execution and options
perldiag Perl diagnostic messages
perllexwarn Perl warnings and their control
perldebtut Perl debugging tutorial
perldebug Perl debugging

perlvar Perl predefined variables
perllol Perl data structures: arrays of arrays
perlopentut Perl open() tutorial
perlretut Perl regular expressions tutorial

perlre Perl regular expressions, the rest of the story
perlref Perl references, the rest of the story

perlform Perl formats

perlboot Perl OO tutorial for beginners
perltoot Perl OO tutorial, part 1
perltootc Perl OO tutorial, part 2
perlobj Perl objects
perlbot Perl OO tricks and examples
perltie Perl objects hidden behind simple variables

perlipc Perl interprocess communication
perlfork Perl fork() information
perlnumber Perl number semantics
perlthrtut Perl threads tutorial

perlport Perl portability guide
perllocale Perl locale support
perlunicode Perl unicode support
perlebcdic Considerations for running Perl on EBCDIC platforms

perlsec Perl security

perlmod Perl modules: how they work
perlmodlib Perl modules: how to write and use
perlmodinstall Perl modules: how to install from CPAN
perlnewmod Perl modules: preparing a new module for distribution

perlfaq1 General Questions About Perl
perlfaq2 Obtaining and Learning about Perl
perlfaq3 Programming Tools
perlfaq4 Data Manipulation
perlfaq5 Files and Formats
perlfaq6 Regexes
perlfaq7 Perl Language Issues
perlfaq8 System Interaction
perlfaq9 Networking

perlcompile Perl compiler suite intro

perlembed Perl ways to embed perl in your C or C++ application
perldebguts Perl debugging guts and tips
perlxstut Perl XS tutorial
perlxs Perl XS application programming interface
perlclib Internal replacements for standard C library functions
perlguts Perl internal functions for those doing extensions
perlcall Perl calling conventions from C
perlutil utilities packaged with the Perl distribution
perlfilter Perl source filters
perldbmfilter Perl DBM filters
perlapi Perl API listing (autogenerated)
perlintern Perl internal functions (autogenerated)
perlapio Perl internal IO abstraction interface
perltodo Perl things to do
perlhack Perl hackers guide

perlhist Perl history records
perldelta Perl changes since previous version
perl5005delta Perl changes in version 5.005
perl5004delta Perl changes in version 5.004

perlaix Perl notes for AIX
perlamiga Perl notes for Amiga
perlbs2000 Perl notes for POSIX-BC BS2000
perlcygwin Perl notes for Cygwin
perldos Perl notes for DOS
perlepoc Perl notes for EPOC
perlhpux Perl notes for HP-UX
perlmachten Perl notes for Power MachTen
perlmacos Perl notes for Mac OS (Classic)
perlmpeix Perl notes for MPE/iX
perlos2 Perl notes for OS/2
perlos390 Perl notes for OS/390
perlsolaris Perl notes for Solaris
perlvmesa Perl notes for VM/ESA
perlvms Perl notes for VMS
perlvos Perl notes for Stratus VOS
perlwin32 Perl notes for Windows

All this information at my fingertips fooled me into believing the language was
more usable than it really was (or at least, than I found it). It is
definitely a sign of a mature language and user community.

I wonder what other Ruby folk think of this collection of information, whether
there is any sense or feasability in creating some documentation of this kind
for Ruby. Finding a format to please everybody is difficult: I think man pages
are terrific, but others may not.

Ruby doesn’t even have a manpage on my system (Cygwin). A basic manpage
containing links to the online book, ruby-talk, etc. would be a start.

Cheers,
Gavin

···

----- Original Message -----
From: “Hal E. Fulton” hal9000@hypermetrics.com

----- Original Message -----

54

I feel that in my original post i was specific as i could be. If people
here feel that the the overall online english ruby documentation does not
need improvement, great.

All you’ve said is that the online docs for “modules and methods” was not
complete or thorough - Personally, I think the online Pickaxe book is as
good as any book for any other language in it’s descriptions of the
various built-in classes, modules and methods in the Ruby library.

So I’ll try one more time: Can you give us a specific example where you
found that you needed more information or the information wasn’t clear?
For example, you could say: “The explanation of the foo method in the
module Fooable didn’t tell me anything about how instance
variables of the
class it is being mixed into will be affected”.

If somebody from the “outside” (for lack of a better word) makes a comment
or an observation, those on the “inside” should consider that, all possible
explanations/refutations/rationalizations aside, that is how things appear
to at least one, and probably more, outsider.

Clearly, somebody has a problem locating and using Ruby documentation.

One issue, if I’m reading this right, is that there is no one single place a
developer may go to look for complete documentation on all Ruby classes,
libs and modules. This is a valid concern. The Pick-Axe book covers a lot
of ground, but does not include documentation for every standard library.
For example, I recently needed to understand monitor.rb. Searching the
WinHelp version of the Pick-Axe turned up nothing. The paper version doesn’t
list it in the index.

The source code has some sparse RD doc, but it does not explain the module
or its methods, giving only a rather sparse example. Besides, if you’re new
to Ruby, you need to know what the RD doc format is, and know to go install
rdtool to see it as formatted output. (Oddly, it does not come as part of
the standard installation, even though so much source uses RD.)

ri tells me, “Couldn’t find class/module `MonitorMixin’.”

Searching the ruby-talk archives doesn’t give any doc pointers, either. The
Ruby Developer’s Guide book doesn’t list monitor.rb in the index; neither
does Ruby in 21 Days. The Ruby Way has an entry for monitoring, and turning
to page 378 I see it discusses monitor.rb. OK, so I can read the
description and look over the example. It’s helpful, but, in the end, I
don’t think it’s quite accurate to say monitor.rb is documented in The
Ruby Way.

This isn’t an isolated case, just one that’s fresh in my mind. And it isn’t
meant as a slam on anybody who’s taken the time and effort to contribute to
Ruby development. Not to single out Ruby or any developers, I have a
problem in general with much open-source software and the almost universal
lack of even cursory documentation. (About the only good thing about it is
that it offers opportunities for industrious book writers.)

Now, there can be any number of explanations for this. An obvious one is
that many Ruby developers are not native English speakers. Another reason,
common to pretty much all development, is that developers just don’t like to
write documentation. (When called on this, many simply tell you to read
the source code, as if dismantling a bike will tell you how to ride one.)
Sometimes it’s just a matter of time; writing free software as part of a
busy life doesn’t leave much opportunity for certain niceties.

Ideally, when somebody asks about documentation for such-and-such, we should
be able to say, “try http://some.example.com/docs/such-and-such”, much as
you can do with PHP. We could perhaps start an Adopt a Library program, and
see to it that every bit of Ruby is documented in one place, with a
simple, uniform means of access.

One should also be able to run RDoc or rdtool on the Ruby source tree, and
get reasonable documentation for every class and module.

(By “reasonable documentation” I mean class and module names, a list of
methods and parameters, what the parameters are supposed to be, what the
code is intended to do, circumstances for appropriate use, known problems,
version number, required files, and related classes and modules.)

There was a thread some time back about adding documentation to the 1.7 or
1.8 source, but I don’t know what came of it.

In general, if somebody has a criticism of Ruby, and it takes more than one
succinct sentence to refute the claim, then there’s a problem. (To quote
JC Watts, an American ex-politician, “If you have to explain, you’ve already
lost.” )

We should not shoot the messenger, nor pick apart the comment, nor tell the
person the problem is with him or her. Do not tell the person that, since
he or she has pointed out the problem, he or she should offer to head up a
project to fix it. (Not to say these things have happened in this thread,
but they have happened at different times in the past.)

Documentation needs work, and we need a plan to improve it.
I would be happy to contribute.

Perhaps, as a start, we might get a list of all classes/modules, and find
out who owns each one. See if the owner is willing and able to write any
needed documentation. If not, start looking for somebody to take over that
documentation, and see if the code owner is at least available for
consultation when questions arise.

We would need a documentation repository (perhaps a wiki), agreement on what
the documentation should contain, and what formatting is used.

It would be nice, too, if at the end we had documentation in both Japanese
and English.

James

55

I personally use Ruby as my main scripting language and feel that the
PickAxe book is priceless. Maybe my original post was just a big mistake
:). I was basically just doing a dump of what one company thought when
looking into using ruby as a tool and also what i have seen some online
friends pass through pertaining to using ruby.

Please understand that the only reason we even considered using ruby at
work was because I brought it up often in conversations with coworkers
lately. When my coworkers and project manager presented to each other what
they thought of ruby I thought to myself “if everyone except me thinks
there is not enough documentation, maybe even though I think there is,
there isn’t.” When i started to put ruby to use for small personal
projects the pickaxe book was there and i found it adequate to my
requirements for learning ruby :).

I didn’t want to push the issue at work since everyone came to the same
conclusion except for me. I didn’t want to sound unprofessional or like a
zealot and in the end i really do agree with them even though the docs are
ok for me using ruby at home. as far as the pickaxe book goes, they
basically said the book is good as a starting point/base but felt there
wasnt much solid documentation out there aside from that (maybe i should
mention we are big cookbook style documentation fans? anyway…).
Basically everyone just agreed on this and that was that. It wasnt like we
were trying to figure out and take notes of the weak points in the ruby
documentation so we could present them to the community, it was just a
general conclusion everyone agreed on after 2 weeks of everyone looking
into ruby. I personally decided to do a dump of the decision to the
newsgroup, thinking back, it was probably a bad idea since i never wanted
to get into specifics for the fact that getting into specifics usually
leads into long discussions and i have enough stuff to do, plus
getting into specifics on a topic such as this could lead to me
slipping into a new side project that i don’t have time for nor do i want.
When i say overall and general that is what i mean and for a well
thought-out reason. I was just trying to relay a company’s decision and
let the chips fall where they may, i really thought i was clear about my
intentions in my original post, then again, I’m not a writer.

I’m not going to bring this up at work and ask specifically for
their reasons in detail while i take notes with a pen and paper nor do i
want to ask them to go back and dig some more to make me happy. Doing so
could possibly make me look like i am taking the issue personally and not
letting it drop. My point again with my original post was just to point
out that a team of people at a company looked into using ruby and came to
the conclusion that they really thought the language was great but the
final decision was “no” with the reason of not enough english
documentation. The reason I was mentioning about the python.org’s
docs/module index is because people where i work think python.org’s docs
are fantastic (they also feel the same about perl’s and PHP’s). So for the
sake of sounding very redundant, all i really wanted to do is dump this
experience to the net for others to see, maybe i shouldnt have made the
suggestions of contributing to pleac and to port cpan modules. Anyway, i
do have work plus my own side project going on, the people who are
suggesting i am mouthing off but taking no action, well, you’re right,
i’ll leave the action taking in the ruby community to someone else if they
feel there is some action needed to be taken. So after this post i shut up
:).

I’m guessing (hoping) Hal will read this post, because this pretty much an
answer to both of you. I do appreciate the time Hal took to make his post,
but i just figured i would answer both here. Actually, this is pretty much
to everyone who has posted to this topic, sorry for my original post :).
This really has already taken to much of my time (i’m not trying to sound
important, pretty much i’m not :), but i am very busy), thinking back, i
should have just kept lurking.

sorry for the commotion,
stibbs

···

On Fri, 30 Aug 2002 20:48:02 -0400, Phil Tomson wrote:

In article pan.2002.07.31.23.56.23.344521.11118@nothanks.foo, stibbs
stibbs@nothanks.foo wrote:

In my original post i thought i made it clear that i am referring to the
overall online english documentation for modules/methods and ruby in
general (since that is what i specifically stated in my original post).
I don’t want to get side tracked or off topic on what seems to be a not
so pleasant subject for discussion in this newsgroup. Personally, books
would be a second concern for me until the online english documentation
got up to par organizationally and with the thoroughness and clarity of
python.org’s documentation. This is something the community as a whole
can take part in, where as compared to a book which is usually dictated
by one person or a very small handful of people.

I was just trying to give an inside look at one companies decision
dealing with Ruby. I also happened to mention on a personal note that i
know people that have tried ruby and even though they liked it a lot,
they all eventually made the decision to go back with their prior
scripting language within a few weeks with their reason being an overall
lack of clear and thorough (english) documentation.

So, i got up the balls and decided to make the post just to make sure
people in the community realized that people and possibly companies who
would otherwise be adopting ruby are not due to the english
documentation issue.

If the community already realized this issue to the same extent that i
have observed, I apologize for my original post.

Most, if not all, of Ruby’s built-in modules are documented in
“Programming Ruby”.

So again, could you give us some specific examples of actual

I feel that in my original post i was specific as i could be. If people
here feel that the the overall online english ruby documentation does
not need improvement, great.

All you’ve said is that the online docs for “modules and methods” was
not complete or thorough - Personally, I think the online Pickaxe book
is as good as any book for any other language in it’s descriptions of
the various built-in classes, modules and methods in the Ruby library.

So I’ll try one more time: Can you give us a specific example where
you found that you needed more information or the information wasn’t
clear? For example, you could say: “The explanation of the foo method in
the module Fooable didn’t tell me anything about how instance variables
of the class it is being mixed into will be affected”.

Again, I ask this because the various Ruby documentation out there (the
PickAxe book and online version, Ruby In a Nutshell, The Ruby Way, etc)
all seem to offer a very complete, thorough treatment of the language
and it’s libraries so I really don’t understand your statement about
documentation being incomplete or unclear. Now, perhaps, since I’ve
been using Ruby for a couple of years now and I was used to digging a
little deeper on my own for information before all this wonderful
documentation was available, I don’t see what the problem is now that
documentation seems to be readily available. By way of analogy, if I’ve
always had to walk to get anywhere and someone gives me a bicycle and
then sometime later someone with a car comes a long and says “Hey, your
mode of transportation isn’t as good as it could be, get a car!” I’m
likely to answer “What do you mean, I’m getting around great on this
bike!”. So since you were kind enough to point out an apparent lack of
documentation and want to enlighten us and help out the community it
would be helpful if you could give us a few specific examples of where
you felt the docs were lacking, cases where you and your colleagues were
scratching your heads wondering how you would actually use some class or
or method (and it actually kept you from getting anything done).

No personal attack on you is intended. Look at it this way, you said in
an earlier post that you have an open source project. I suppose that
your project includes docs for how to build, install and use your code.
If someone sent you an email that said: “Dude, I think your program is
great, but your docs suck!” and you asked for some specifics and all you
got back is: “Dude, the docs for how to use your system are lacking and
I’m gonna use a different program because of it.” wouldn’t you find that
a wee bit frustrating?

Phil

56

The best course of action is generally to pay some attention to all
the conversation, but not too much attention to the conversation
involving people not actually doing anything. Saves much hassle and
aggrivation.

So, discussing a problem should not be considered doing something?
What’s the criteria for “doing something”?

James

···

–
Dan

--------------------------------------“it’s like this”-------------------
Dan Sugalski even samurai
dan@sidhe.org have teddy bears and even
teddy bears get drunk

57

In article 3D767065.1848339A@johnknight.com,

···

John Knight john@johnknight.com wrote:

One new possibility is wiki.

I suggest people decide on a man style format. Even if it is not
compleltely standard from the start it will evolve. Finally, all
documentation be put on a wiki with version control. Anybody can modify
or annotate the docs and after some time a people wishing to earn a
reputation as a writer can review the history of documentation changes
and evolve the documentaton to the next level.

    • This already exists.

http://www.ruby-lang.org/~rubikitch/RDP-en.cgi?cmd=view;name=top

    • Booker C. Bense
58

Hi

I have been programming Ruby on a daily basis for
over 18 months now. As I look back I think, wow, that
is a long time to be so singularly committed to a
programming language (ok, so I may be a little weird,
but wait a minute… I think that is a given for
programmer types…). Over that time, I have received
support from the courteous and intelligent folks on this
list. So, after 18 months experiencing the joy of
programming in Ruby, I think it is time to show
my thanks and my commitment by repaying some of my
debt to the Ruby cummunity.

Therefore, if I may be so bold, I would like to
volunteer to head the documentation standardization
probject for Ruby. I am sure there are many that
may be more qualified or do a better job at this.
If so, I will gladly step aside for anyone who
feels particularly called to do this activity.
As for myself, I think it is important enough
to warrant action sooner rather than later. Thus,
the reason for my proposal.

I have followed the discussions on this subject and
there have been many good comments. But now I think
it is an appropriate time to inject a little organization
into this project and move it forward on a steady basis.

Below is a list of actions that I think will help get
our cause started:

  1. Form a ruby-doc mailing list to begin discussions
    related to documentation.
  2. Form a Ruby Document Organizing Committee (RDOC)
    for purpose of officially reviewing the document
    standardization process and voting on
    decisions (of course Matz has ultimate veto power).
  3. Start a web page to publicize the activities
    of the documentation project.
  4. Start the paper work for the standardization process.
    a Gather Requirements and write Requirements specification.
    i. get feedback from community
    ii. have committee review and approve
    b. Write functional specification
    i. get feedback from community
    ii. have committee review and approve
    c. Create design document
    i. get feedback from community
    ii. have committee review and approve
    4. Implement RDOC process and develop tools
    5. Integrate 4 into releases of Ruby

I welcome your comments along the lines:

a) this is a good idea, let’s get going
and I want to be on the committee
b) what, are you crazy??
c) good idea, but I can do a lot better
job than you…
d) it’s all hopeless, I am going back to
programming in perl.

Cheers

···

–
Jim Freeze

Programming Ruby
def initialize; fun; end
A language with class

59

W Kent Starr wrote:

stibbs has pointed out what he believes to be a widespread perception
that may be holding back the adoption of Ruby; to that extent, IMO it is
an issue the community should address, whether in fact it is or not an
issue within the community.

The problem I think is that for a Perl or Python shop then Ruby might be
better but not to the extent that moving from C to Perl was.

It takes a programmer to see the advantages of Ruby whereas a suit could
see the results / advantages of Perl over C (faster development, quicker
fixes and CPAN).

Don’t underestimate CPAN, here if we have a problem we click over to
CPAN pick up a module and away we go, it doesn’t matter that it is just
a wrapper around a .so as far as appearances go Perl has provided a
solution and it was quick and easy.

The reason that I don’t use Python that much is because it wasn’t /that
much better/ than Perl (and Perl has CPAN).

The reason I still haven’t dumped Java is the copious libraries (no
matter how badly designed) and especially Swing.

Perl => CPAN
Java => The API
Ruby => ?

There is more to the acceptance of a language than the syntax.

60

I personally use Ruby as my main scripting language and feel that Dave’s
book is priceless. Maybe my original post was just a big mistake :). I was
basically just doing a dump of what one company thought when looking into
using ruby as a tool and also what i have seen some online friends pass
through pertaining to using ruby.

Please understand that the only reason we even considered using ruby at
work was because I brought it up often in conversations with coworkers
lately. When my coworkers and project manager presented to each other what
they thought of ruby I thought to myself “if everyone except me thinks
there is not enough documentation, maybe even though I think there is,
there isn’t.” When i started to put ruby to use for small personal
projects the pickaxe book was there and i found it adequate to my
requirements for learning ruby :).

I didn’t want to push the issue at work if everyone came to the same
conclusion except for me (I didn’t want to sound unprofessional or like a
zealot). I did bring up the pickaxe book and they basically said the
book is good as a starting point/base but felt there wasnt much out there
after that (i should mention we are big cookbook style documentation
fans). Basically everyone just agreed on this and that was that. It wasnt
like we were trying to figure out and take notes of the weak points in the
ruby documentation so we could present it to the community, it was just a
general conclusion everyone agreed on after 2 weeks of everyone looking
into ruby. I personally decided to do a dump of the decision to the
newsgroup, thinking back, it was probably a bad idea since i never wanted
to get into specifics for the fact that getting into specifics usually
draws out into long discussions and i have enough work as it is. I was
just trying to relay a company’s decision and let the chips fall where
they may, i really thought i was clear about my intentions in my original
post but then again I’m not a writer.

I really don’t want to bring this up at work and ask specifically for
their reasons or ask them to go back and dig some more to make me happy
:), this could possibly make me look like i am taking the issue personally
and not letting it drop. My point again with my original post was just to
point out that a team of people at a company looked into using ruby and
came to the conclusion that they really thought the language was great but
the final decision was “no” with the reason of not enough english
documentation. The reason I was mentioning about the python.org’s
docs/module index is because people where i work think they are fantastic.
So for the sake of sounding redundant, all i really wanted to do is dump
this experience to the net for others to know, maybe i shouldnt have made
the suggestions of contributing to pleac and to port cpan modules. Anyway,
i do have work plus my own side project going on, the people who are
suggesting i am mouthing off but taking no action, well, you’re right,
i’ll leave the action in the ruby community to someone else if they feel
there is some needed to be taken. so now i shut up :).

I’m guessing (hoping) Hal will read this post, because this pretty much an
answer to both of you. I do appreciate the time Hal took to make his post,
but i just figured i would answer both here. Actually, this is pretty much
to everyone who has posted to this topic, sorry for my original post :).
This really has already taken to much of my time (i’m not trying to sound
important, pretty much i’m not :), but i am very busy), thinking back, i
should have just kept lurking.

sorry for the commotion,
stibbs

···

On Fri, 30 Aug 2002 20:48:02 -0400, Phil Tomson wrote:

In article pan.2002.07.31.23.56.23.344521.11118@nothanks.foo, stibbs
stibbs@nothanks.foo wrote:

In my original post i thought i made it clear that i am referring to the
overall online english documentation for modules/methods and ruby in
general (since that is what i specifically stated in my original post).
I don’t want to get side tracked or off topic on what seems to be a not
so pleasant subject for discussion in this newsgroup. Personally, books
would be a second concern for me until the online english documentation
got up to par organizationally and with the thoroughness and clarity of
python.org’s documentation. This is something the community as a whole
can take part in, where as compared to a book which is usually dictated
by one person or a very small handful of people.

I was just trying to give an inside look at one companies decision
dealing with Ruby. I also happened to mention on a personal note that i
know people that have tried ruby and even though they liked it a lot,
they all eventually made the decision to go back with their prior
scripting language within a few weeks with their reason being an overall
lack of clear and thorough (english) documentation.

So, i got up the balls and decided to make the post just to make sure
people in the community realized that people and possibly companies who
would otherwise be adopting ruby are not due to the english
documentation issue.

If the community already realized this issue to the same extent that i
have observed, I apologize for my original post.

Most, if not all, of Ruby’s built-in modules are documented in
“Programming Ruby”.

So again, could you give us some specific examples of actual

I feel that in my original post i was specific as i could be. If people
here feel that the the overall online english ruby documentation does
not need improvement, great.

All you’ve said is that the online docs for “modules and methods” was
not complete or thorough - Personally, I think the online Pickaxe book
is as good as any book for any other language in it’s descriptions of
the various built-in classes, modules and methods in the Ruby library.

So I’ll try one more time: Can you give us a specific example where
you found that you needed more information or the information wasn’t
clear? For example, you could say: “The explanation of the foo method in
the module Fooable didn’t tell me anything about how instance variables
of the class it is being mixed into will be affected”.

Again, I ask this because the various Ruby documentation out there (the
PickAxe book and online version, Ruby In a Nutshell, The Ruby Way, etc)
all seem to offer a very complete, thorough treatment of the language
and it’s libraries so I really don’t understand your statement about
documentation being incomplete or unclear. Now, perhaps, since I’ve
been using Ruby for a couple of years now and I was used to digging a
little deeper on my own for information before all this wonderful
documentation was available, I don’t see what the problem is now that
documentation seems to be readily available. By way of analogy, if I’ve
always had to walk to get anywhere and someone gives me a bicycle and
then sometime later someone with a car comes a long and says “Hey, your
mode of transportation isn’t as good as it could be, get a car!” I’m
likely to answer “What do you mean, I’m getting around great on this
bike!”. So since you were kind enough to point out an apparent lack of
documentation and want to enlighten us and help out the community it
would be helpful if you could give us a few specific examples of where
you felt the docs were lacking, cases where you and your colleagues were
scratching your heads wondering how you would actually use some class or
or method (and it actually kept you from getting anything done).

No personal attack on you is intended. Look at it this way, you said in
an earlier post that you have an open source project. I suppose that
your project includes docs for how to build, install and use your code.
If someone sent you an email that said: “Dude, I think your program is
great, but your docs suck!” and you asked for some specifics and all you
got back is: “Dude, the docs for how to use your system are lacking and
I’m gonna use a different program because of it.” wouldn’t you find that
a wee bit frustrating?

Phil