Documentation standard

[cyberco]

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.
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.

Kind regards,
CyBerco

 

[Keith P. Boruff]

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.
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.

KPB

 

[James Britt]

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

 

[Zach Dennis]

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

Zach

 

[James Britt]

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.

James

 

[Zach Dennis]

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. =)

Zach