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 D.
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
Hi –
On Tue, 2 Jan 2007, Mark D. 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 (Ruby for Rails)
(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)
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 D. [email protected] 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:
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.
Wasn’t there some fund raiser for documentation?
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:
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
On 1/3/07, Jeremy McAnally [email protected] 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 T. 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 =).
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 T.
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 S. [email protected] wrote:
I think maybe they need to take someone who’s passionate about it, let
It really sounds like they are expecting Dave T. or David Black to
- Rob
–
http://www.robsanheim.com
http://www.seekingalpha.com
http://www.ajaxian.com
–
“Impossible is nothing.”
Yes, and you can read more about it here:
http://blog.caboo.se/articles/2006/12/27/update-on-the-documentation-project#comments
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 [email protected] 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 thatTonypm
–
My free Ruby e-book:
http://www.humblelittlerubybook.com/book/
My blogs:
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
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.
Mark D. 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
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 F. [email protected] 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:
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 F. [email protected] wrote:
annotations - gotchas, known issues, examples, etc ?
A.
–
Posted via http://www.ruby-forum.com/.
–
Cell: 808 782-5046
Current Location: Melbourne, FL
This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.
Sponsor our Newsletter | Privacy Policy | Terms of Service | Remote Ruby Jobs