James Britt
1/22/2005 3:16:00 AM
cyberco wrote:
> Hello!
>
> 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.
James