Forum: Ruby on Rails Rails API Documentation

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Df6805f12a6120f840e218fd883958a6?d=identicon&s=25 Mark Dodwell (mkdynamic)
on 2007-01-02 16:03
In my opinion there is no good online version of the Rails API
Documentation.

So I have been considering creating one myself. With that in mind I
thought it'd be wise to ask people two things:

a) Do you agree there is no good version?

b) What are the things that would make a really good version?

Your feedback will help me to decide if I should go ahead, and what I
should aim for if I do - so thanks in advance!

Best,

Mark Dodwell
6d3c187a8b3ef53b08e3e7e8572c4fea?d=identicon&s=25 Jeremy McAnally (Guest)
on 2007-01-02 16:29
(Received via mailing list)
What makes the current versions bad in your opinion?  Or, should I
say, what features are lacking?  Is it the API documentation itself or
the applications running the online versions?

Have you look at http://www.railsmanual.com/ ?  Or
http://caboo.se/doc.html ? Or http://www.railsapi.org/ ?

Between one of these three or the standard one at
http://api.rubyonrails.org/ , I don't think I would need anything
else.

--Jeremy
1fba4539b6cafe2e60a2916fa184fc2f?d=identicon&s=25 unknown (Guest)
on 2007-01-02 16:29
(Received via mailing list)
Hi --

On Tue, 2 Jan 2007, Mark Dodwell wrote:

>
> In my opinion there is no good online version of the Rails API
> Documentation.
>
> So I have been considering creating one myself. With that in mind I
> thought it'd be wise to ask people two things:
>
> a) Do you agree there is no good version?

No.

> b) What are the things that would make a really good version?

Apparently I don't know :-)  It's possible that there are things an
online version could do that I've never thought of, and that I'd find
useful if I saw them.  I've always found api.rubyonrails.org pretty
complete and easily navigable.


David

--
Q. What is THE Ruby book for Rails developers?
A. RUBY FOR RAILS by David A. Black (http://www.manning.com/black)
    (See what readers are saying!  http://www.rubypal.com/r4rrevs.pdf)
Q. Where can I get Ruby/Rails on-site training, consulting, coaching?
A. Ruby Power and Light, LLC (http://www.rubypal.com)
Df6805f12a6120f840e218fd883958a6?d=identicon&s=25 Mark Dodwell (mkdynamic)
on 2007-01-02 16:49
Thanks for your comments.

I think the content of the API's is in general good, although I have
come across occasions where it is incorrect.

My top issue with the current online versions is the poor interface. I
would say this for the ones I've found so far, specifically:

http://www.railsmanual.com/
http://caboo.se/doc.html
http://www.railsapi.org/
http://api.rubyonrails.org/

For example, searching is poor. In all but http://www.railsapi.org, if
you just enter a simple term 'has_many' you won't easily find that
method without rumaging through lots of false matches.

One simple thing - there are lots of character encoding problems

Also browsing the source could be made much easier. A hierarchial
organisation would be much more helpful than the flat one (i.e. a long
list of files, classes, or methods).

This is a doc that many people are using all day long everyday, and so
it should be reasonable to expect a very easy interface.

I think that http://www.railsapi.org is the best of the bunch, but still
I don't feel particualary happy with it. Why is the search box not more
prominent on the homepage, why is all that space taken up by the top
banner for no reason?

But, maybe it's just me - but I don't think any of them are well
designed or structured to make finding things easy.
6d3c187a8b3ef53b08e3e7e8572c4fea?d=identicon&s=25 Jeremy McAnally (Guest)
on 2007-01-02 17:02
(Received via mailing list)
A smarter source browser would be nice, especially when trying to
understand the internals of Rails, as would a smarter search.  I've
been running my own local Ferret app to do doc searching, so I rarely
use the API searches on there unless I don't want to spend the time to
open a terminal up. ;)

--Jeremy

On 1/2/07, Mark Dodwell <rails-mailing-list@andreas-s.net> wrote:
> http://caboo.se/doc.html
> organisation would be much more helpful than the flat one (i.e. a long
> But, maybe it's just me - but I don't think any of them are well
> designed or structured to make finding things easy.
>
> --
> Posted via http://www.ruby-forum.com/.
>
> >
>


--
My free Ruby e-book:
http://www.humblelittlerubybook.com/book/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/
Db7238007950074e9e73b76a81910406?d=identicon&s=25 tonypm (Guest)
on 2007-01-03 22:50
(Received via mailing list)
Hi,

it is quite difficult to define what is lacking in documentation, until
the time comes when one is trying to get something to work and cant
figure out how to do it.  Having now been learning Rails (and Ruby) for
several months, and not coming from a strong web programming
background, I will try to say what I have found most difficult.

The whole subject of Rails, covers an enormous breadth, and to the
newcomer, it is difficult to know how to drill into it.  The various
tutorials around the web cover the basics of creating a simple app, but
when it comes to wanting to do specific things it is difficult to know
how to get at the information you want.  It is almost always out there
somewhere, but it involves picking up bits and pieces from the forums,
tutorials, manual, wiki and api.

I think that the problems I have faced have been 2 sided.  On the one
front, when I find a method that appears to do what I want
(particularly with some of the helpers), it is not always clear how to
use it.  The explanation is just that bit lacking.  It is fine when you
know what it does, but getting there in the first place takes too long.
 Often just a few more words would clarify how they work, particularly
with respect to the argument lists.

On the other front, is the difficult problem of "I know there is a
method that does just what I want, but I cant remember what it is
called - eg.  was it pluralise, capitalise, humanise? just what was
that method that changes to this_case to ThisCase.  Some of these are
difficult to put into meaningful phrases so even google does not always
help.  Perhaps it's not actually in Rails, but in Ruby I should be
looking.

There are lots of cheat sheets around, but invariably what I am looking
for is not in them.

There is no doubt the the Agile Rails book is incredibly useful, but
sometimes even using that it has taken ages to find the specific thing
I am looking for.

I really dont know if any of this helps, but perhaps it sumarises as:

1.  Improved explanations
2.  more simple/short examples
3.  consolidation of all of the resources
4.  Indexing/cross referencing/searchability

The php manual is pretty good it is quite well structured and indexed,
functions/methods are described and the comments added by the community
serve to provide examples and clarifications.

I appreciate that php is a language and Rails is a framework and that
in itself is another problem.

BTW, wasn't there an initiative a while ago to take on a professional
full time documentation person.  If someone has been looking at this
now for quite a few weeks, perhaps some ideas and approaches may be
developing.  One danger I can see is for various different versions of
documentation to appear on different sites.  It is already difficult
enough to remember where I saw a particular bit of information, but if
several sites pop up trying to document Rails in different ways, it
could become a greater problem.

Tonypm
F90ae3341c0dae4fb1795075485688c3?d=identicon&s=25 kirkr (Guest)
on 2007-01-03 23:06
(Received via mailing list)
Wasn't there some fund raiser for documentation?
6d3c187a8b3ef53b08e3e7e8572c4fea?d=identicon&s=25 Jeremy McAnally (Guest)
on 2007-01-03 23:18
(Received via mailing list)
Yes, and you can read more about it here:
http://blog.caboo.se/articles/2006/12/27/update-on...

Basically, no one up to their standards wants to do it/has time to do
it.  It's understandable that they want someone capable to do it, but
I think maybe they need to take someone who's passionate about it, let
them do it, and let them be overseen by a "published author" rather
than expecting a published author to do it (especially since most of
them are probably working on other books, teaching, or, like, working
on software or something ;)).

Another option would be to open it up to the community, let them write
it, and have that overseen by a panel of authors that proofread, edit,
fill out, or otherwise mangle the text into a usable form.  I'd be
willing to contribute.

But, hey, they're the ones with the money. :)

--Jeremy

On 1/3/07, kirkr <ellisdee@gmail.com> wrote:
> > background, I will try to say what I have found most difficult.
> > front, when I find a method that appears to do what I want
> > difficult to put into meaningful phrases so even google does not always
> > I really dont know if any of this helps, but perhaps it sumarises as:
> > I appreciate that php is a language and Rails is a framework and that
> >
> > Tonypm
>
>
> >
>


--
My free Ruby e-book:
http://www.humblelittlerubybook.com/book/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/
Df5e7adb20adae6c120b04e7cafb15a0?d=identicon&s=25 Rob Sanheim (rsanheim)
on 2007-01-04 00:03
(Received via mailing list)
On 1/3/07, Jeremy McAnally <jeremymcanally@gmail.com> wrote:
> on software or something ;)).
>
> Another option would be to open it up to the community, let them write
> it, and have that overseen by a panel of authors that proofread, edit,
> fill out, or otherwise mangle the text into a usable form.  I'd be
> willing to contribute.

It really sounds like they are expecting Dave Thomas or David Black to
step up and take charge of the project.  I think anyone who is as
talented as guys of that caliiber already have more then their share
of work.  The caboose guys just need to hire someone who is passionate
and smart but also new enough where he isn't overloaded with
consulting/writing/etc.  I think once they get an actual deliverable
up and on the web, more help will come as it won't be a giant empty
project with no results.

IOW, just get started with something crappy, then worry about making
it really good =).

- Rob

--
http://www.robsanheim.com
http://www.seekingalpha.com
http://www.ajaxian.com
1b6ed15a6126e1d5ef4d7d15550f30bb?d=identicon&s=25 François Montel (zerohalo)
on 2007-01-04 00:27
(Received via mailing list)
I agree with a previous poster who stated that the lack of examples and
further explanations on some methods is a roadblock. I often find myself
experimenting with a method simply because the explanation in the Rails
API
is unclear or the examples are incomplete, or certain method parameters
are
not explained. Of course I don't expect the Rails core team to spend
their
time writing docs. That is why I think that the approach taken by
railsmanual.org and railsapi.org is the way to go - have it be a
community-driven effort, with an editor approving content in order to
make
sure that it's accurate (that could also be done by peer review if the
website had that ability built-in; ie, 2 other registered users have to
vet
a comment or example before it is approved).  It's a pity though that
efforts are being divided with some people adding comments/examples to
railsmanual, others to railsapi, yet others to tho caboo.se effort. It
would
be helpful if the Rails community united behind a single site that
became
"the standard" that everyone contributed to. Not to put down the various
efforts that have been made--they're great, but it seems we need an
"opinionated" approach to the documentation. Maybe if DHH or the Rails
Core
team, or a group of Ruby/Rails heavyweights like Dave Black, Dave Thomas
and
others, gave their blessing to a particular site and urged the community
to
contribute, we'd see faster progress.



On 1/3/07, Rob Sanheim <rsanheim@gmail.com> wrote:
> > I think maybe they need to take someone who's passionate about it, let
> It really sounds like they are expecting Dave Thomas or David Black to
>
> - Rob
>
> --
> http://www.robsanheim.com
> http://www.seekingalpha.com
> http://www.ajaxian.com
>
> >
>


--
"Impossible is nothing."
99dfa3f52932cfa4dab2a7ae6dd7ef39?d=identicon&s=25 Tony (Guest)
on 2007-01-04 15:10
Hi there !

As everybody, I'm missing some documentation/examples. Time to time, I
can now give some tips to my coworker to start with Rails.

An online doc I like is : http://www.gotapi.com/

It's not full of example, neither it has more documentation than the
plain old school rails API doc. But I think the searchable part and the
classification are quite clear and usefull.

And thanks for the railsapi.org link : it's quiete good and I will try
to contribute.

Tony
4daf0b71d5d9a3882e583c0e72eaf5dc?d=identicon&s=25 Alan Francis (Guest)
on 2007-01-04 17:22
Jeremy McAnally wrote:

> Another option would be to open it up to the community, let them write
> it, and have that overseen by a panel of authors that proofread, edit,
> fill out, or otherwise mangle the text into a usable form.  I'd be
> willing to contribute.

Maybe a wikipedia style site for the rails docs.   I'd like to see more
than just API documentation.  It'd be nice to have user-submitted
annotations - gotchas, known issues, examples, etc ?

A.
D309592f2a210d745b8044847b214bb6?d=identicon&s=25 Jeremy Durham (Guest)
on 2007-01-04 21:42
Mark Dodwell wrote:
> Thanks for your comments.
>
> I think the content of the API's is in general good, although I have
> come across occasions where it is incorrect.
>
> My top issue with the current online versions is the poor interface. I
> would say this for the ones I've found so far, specifically:
>
> http://www.railsmanual.com/
> http://caboo.se/doc.html
> http://www.railsapi.org/
> http://api.rubyonrails.org/
>
> For example, searching is poor. In all but http://www.railsapi.org, if
> you just enter a simple term 'has_many' you won't easily find that
> method without rumaging through lots of false matches.
>
> One simple thing - there are lots of character encoding problems
>
> Also browsing the source could be made much easier. A hierarchial
> organisation would be much more helpful than the flat one (i.e. a long
> list of files, classes, or methods).
>
> This is a doc that many people are using all day long everyday, and so
> it should be reasonable to expect a very easy interface.
>
> I think that http://www.railsapi.org is the best of the bunch, but still
> I don't feel particualary happy with it. Why is the search box not more
> prominent on the homepage, why is all that space taken up by the top
> banner for no reason?
>
> But, maybe it's just me - but I don't think any of them are well
> designed or structured to make finding things easy.

At least in my case, http://www.railsapi.org came out of a personal
need. If there's something you don't like about it, that makes sense,
just shoot me an email and I'll try to take care of it. I think your
points about the banner and the search box are perfectly valid. I've
already had some great feedback from people and have done my best to
accomodate things that were lacking.

Jeremy
6d3c187a8b3ef53b08e3e7e8572c4fea?d=identicon&s=25 Jeremy McAnally (Guest)
on 2007-01-06 19:30
(Received via mailing list)
We have/had a wiki for Rails, but it was so overrun with spam and junk
that it's (mostly) useless now.

I was thinking more along the lines of a panel of authors construct a
TOC or structure the APIs in such a way that is logical, then users
sign up for or submit pieces of text and the authors finesse that data
into a very fine manual.

But I'm not sure how the caboose folks are planning on doing it.

--Jeremy

On 1/4/07, Alan Francis <rails-mailing-list@andreas-s.net> wrote:
> annotations - gotchas, known issues, examples, etc ?
>
> A.
>
> --
> Posted via http://www.ruby-forum.com/.
>
> >
>


--
My free Ruby e-book:
http://www.humblelittlerubybook.com/book/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/
31254903db793bf6f84bbd607fe092fd?d=identicon&s=25 Anthony Eden (Guest)
on 2007-01-06 19:30
(Received via mailing list)
One step ahead of ya:

http://en.wikibooks.org/wiki/Ruby_on_Rails

Feel free to contribute.

V/r
Anthony

On 1/4/07, Alan Francis <rails-mailing-list@andreas-s.net> wrote:
> annotations - gotchas, known issues, examples, etc ?
>
> A.
>
> --
> Posted via http://www.ruby-forum.com/.
>
> >
>


--
Cell: 808 782-5046
Current Location: Melbourne, FL
This topic is locked and can not be replied to.