M. Edward (Ed) Borasky wrote:
Well ... I guess that depends on which docs you are talking about.
There's plenty of documentation on Rails, three of the major GUIs --
Shoes, FXRuby and QtRuby -- have books in "print" on them, there are two
major Ruby "cookbooks", the documentation on Ruport and RSpec is
excellent, etc.
I shouldn't have to buy a book (like the PickAxe), to get decent
documentation. A book should be one option, among many, to get to the
documentation. I'll elaborate on that in the next paragraph.
A week or so ago when the Ruby Mendicant was considering working on the
docs, I expressed the opinion that the documentation is the
responsibility of the creator -- someone shouldn't have to do it for
them. Now if the creator is a better coder than tech writer, perhaps the
project can take on someone. But my experience has been that it's very
rare for someone to be an excellent coder and a poor tech writer.
While I agree, that the project is responsible for its own documentation
~ (its rather obvious, is it not?), the tools we have in the Ruby
community to create documentation are limited to RDoc, a rather hacky
solution (Correct me if I'm wrong, but Dave Thomas said as much),
intended as a stand-in until a more useful tool comes around.
Sadly, as it is so common in the world, the temporary solution becomes
the permanent solution, with all its short-comings (see a discussion on
the mixup of Ruby Core and Ruby StdLib documentation on
ruby-doc.org/core). And that is a big obstacle, making it unnecessarily
difficult for newbies like me (I still am a newbie to Ruby, despite
using it for more than a year, the language is just that complex in its
simplicity, which is a major appeal for me, but that is a rant for
another time).
We, as a community, have to provide tools that make it easy and painless
to generate documentation, and generate it in different formats. In my
most humble opinion, we should take a look at Javadoc, and see what we
can steal^H^H^H^H^H implement for Ruby. I fully recognize that Javadoc
is great for Java, and less so for Ruby, but that doesn't mean it
doesn't have useful ideas that make it a breeze to generate documentation.
Anecdotal evidence: When building the gem for Gondor Library I was
struggling in including the README and LICENSE files in RDoc. The files
were included in my Rake task's FileList for gem generation, as well as
standalone doc generation.
However, the gem didn't include the files in ./, only ./lib, much unlike
the RDoc task. I had to explicitly tell the gem, to include extra files.
I lost more than an hour to that. The outdated RubyGems documentation
didn't really help. Fortunately, I found other Rake tasks, and could
eliminate the problem.
But it shouldn't be this way, and I have the feeling it is a shortcoming
of RDoc (maybe not, I haven't looked at RDoc itself, so my assessment of
the reason maybe wrong, but my point still stands).
Also, that RDoc generates frames for usage isn't the ideal solution,
IMO, as it makes search difficult (via a browser's search, anyway).
And AFAIK, RDoc cannot spit out PDFs, PostScript, or LaTeX, or something
other than ri. And that makes it unnecessarily difficult to generate
non-RDoc documentation without third party tools (and I don't really
want to learn Yet Another Tool that is not directly related to
increasing my productivity in writing Code (that's what I want to do,
not write comments or documentation).
2. My main concern is not with the documentation. My main concern is
that both the syntax and semantics of the language seem to be more fluid
than "pragmatic" considerations would dictate. I more or less grew up
with FORTRAN, although I missed FORTRAN I. So I'll use its evolution as
an example.
Ten years into its evolution, an ANSI committee was formed to
standardize the language. Users and vendors sat around a huge table and
thrashed out what would break the least code, what was easy to
implement, what kinds of programs people wanted to write in the language
that they couldn't, etc. The result was FORTRAN 66. 11 years later there
was FORTRAN 77, etc.
C and C++ went the other way, with the STDLIB growing steadily, and new
features being added. Yet, C/C++ are more in use.
However, both FORTRAN and C are anecdotal evidence. The scope of the
languages is not really the same, and neither is Ruby's.
I think there are enough "killer apps" now that we know what we can't
take out of Ruby without breaking Rails, RSpec, Ruport, etc. And from
MRI, KRI, jRuby and Rubinius, I think we know what's easy to implement
and what isn't. But what I have no clues about is what programs people
want to write in Ruby that they can't write now.
For the power that Ruby gives me: I want to write everything in Ruby.
It's good at pretty much everything I can throw at it, except
number-crunching. But I can farm that out to C or Java, or maybe .NET
once IronRuby is "production ready".
Personally, I haven't reached the point where I feel that Ruby isn't up
to the task at hand, or severely limited. That's anecdotal, though. I'm
sure that people who have to do some heavy lifting and datamunging to do
have a different opinion on that (but more related to Ruby's speed, than
Ruby's syntax and expressiveness, or am I mistaken?).
- --
Phillip Gawlowski
Twitter: twitter.com/cynicalryan
~ - You know you've been hacking too long when...
...you dream that your SO and yourself are icons in a GUI and you can't get
close to each other because the window manager demands minimum space between
icons...
