I just got started with Ruby after years of Java and I'm having a lot
of fun with it! Especially with the pragmatic programmer's book by my
side.
There's one thing that reduces the fun I have: the way Ruby libraries
are documented. Even the documentation of the standard and the core
APIs are below par if you ask me. That's one thing the Ruby community
can learn from the Java community: how to do proper documentation.
Additional Java APIs are easy to find and the API docs always look the
same, which makes it very easy to get started with a new API. In Ruby
new APIs are harder to find and it's always the question if there is
any documentation and what it will look like.
I just got started with Ruby after years of Java and I'm having a lot
of fun with it! Especially with the pragmatic programmer's book by my
side.
There's one thing that reduces the fun I have: the way Ruby libraries
are documented. Even the documentation of the standard and the core
APIs are below par if you ask me. That's one thing the Ruby community
can learn from the Java community: how to do proper documentation.
Additional Java APIs are easy to find and the API docs always look the
same, which makes it very easy to get started with a new API. In Ruby
new APIs are harder to find and it's always the question if there is
any documentation and what it will look like.
All other things about Java aside, it does provide some good documentation.
But Ruby's is getting better. I'm in the same boat as you (learning Ruby) and am finding this site: http://www.ruby-doc.org useful.
Also, I actually bought the most updated Pragmatic Programmer's book instead of viewing the free online first edition. It has a few more things in it from what I can see.
BTW, I think it's fun too. It's a nice diversion from the "uppity C++" stuff that I usually do.
I just got started with Ruby after years of Java and I'm having a lot
of fun with it! Especially with the pragmatic programmer's book by my
side.
There's one thing that reduces the fun I have: the way Ruby libraries
are documented. Even the documentation of the standard and the core
APIs are below par if you ask me. That's one thing the Ruby community
can learn from the Java community: how to do proper documentation.
I don't think it's a matter of people not knowing how to do something, but maybe more that Ruby does not have the funding of a major corporation.
That's not to make excuses; developers really should be writing adequate docs, but when you're juggling a regular job and possibly a real life with writing code and docs for free, certain things (sadly) fall by the wayside.
Additional Java APIs are easy to find and the API docs always look the
same, which makes it very easy to get started with a new API. In Ruby
new APIs are harder to find and it's always the question if there is
any documentation and what it will look like.
If the docs are created using RDoc then they will probably look like other Ruby API docs, though there are options for changing the template.
But when folks write how-to's and so on, they usually follow whatever style pleases the author.
I just got started with Ruby after years of Java and I'm having a lot
of fun with it! Especially with the pragmatic programmer's book by my
side.
There's one thing that reduces the fun I have: the way Ruby libraries
are documented. Even the documentation of the standard and the core
APIs are below par if you ask me. That's one thing the Ruby community
can learn from the Java community: how to do proper documentation.
On a side note, I am in the process of writing a java-api like generator for rdoc for wxRuby, because the wxRuby folks don't care much for default rdoc style browsing... i'll keep the list posted the farther i get, i just started yesterday.
so maybe this will ease some pain, just by how the information is displayed to the user
so maybe this will ease some pain, just by how the information is displayed to the user
There was also a thread (and sorry if this is old news; I didn't follow the whole thing) here about writing alternate RDoc templates that did not use the current frameset format.
so maybe this will ease some pain, just by how the information is displayed to the user
There was also a thread (and sorry if this is old news; I didn't follow the whole thing) here about writing alternate RDoc templates that did not use the current frameset format.
yep, i was on one of those and I started one with the subject of "RDOC Flexbility".
A template is what I plan to do. If the flexibility is there, then awesome, otherwise I'll right wrapper code to modify the rdoc output to what i need. my guess is a template will just do. =)