Rails - Jan 2007 - Rails API Documentation

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

-- 
Posted via http://www.ruby-forum.com/.

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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

On 1/2/07, Mark Dodwell
<rails-mailing-list-ARtvInVfO7ksV2N9l4h3zg@public.gmane.org>
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?
>
> 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
>
> --
> Posted via http://www.ruby-forum.com/.
>
> >
>
--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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)

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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.

-- 
Posted via http://www.ruby-forum.com/.

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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-ARtvInVfO7ksV2N9l4h3zg@public.gmane.org>
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.
>
> --
> 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/

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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


--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Wasn''t there some fund raiser for documentation?

On Jan 3, 3:47 pm, "tonypm"
<tonypmar...-PkbjNfxxIARBDgjK7y7TUQ@public.gmane.org>
wrote:
> 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

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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 <ellisdee-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
>
> Wasn''t there some fund raiser for documentation?
>
> On Jan 3, 3:47 pm, "tonypm"
<tonypmar...-PkbjNfxxIARBDgjK7y7TUQ@public.gmane.org> wrote:
> > 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
>
>
> >
>

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

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

On 1/3/07, Jeremy McAnally
<jeremymcanally-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
>
> 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.
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

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
>
>
> On 1/3/07, Jeremy McAnally
<jeremymcanally-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> >
> > 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.
>
> 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
>
> >
>

-- 
"Impossible is nothing."

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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

-- 
Posted via http://www.ruby-forum.com/.

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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.

-- 
Posted via http://www.ruby-forum.com/.

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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-ARtvInVfO7ksV2N9l4h3zg@public.gmane.org>
wrote:
>
> 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.
>
> --
> 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/

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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-ARtvInVfO7ksV2N9l4h3zg@public.gmane.org>
wrote:
>
> 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.
>
> --
> Posted via http://www.ruby-forum.com/.
>
> >
>

-- 
Cell: 808 782-5046
Current Location: Melbourne, FL

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

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

-- 
Posted via http://www.ruby-forum.com/.

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

A concept I just came up with which may work really well is to have a
user/member only wiki with open comments.

So anyone can create an account for the wiki (with email verified) and
once they have, they can create new pages. Once the page has been
created, users can submit comments to the page similar to the PHP.net.

It would be a combo of a wiki with comments.

I really like the setup railsmanual.org has which I maintain that is
based on the Rannotate RDOC enhancements, but it''s still nowhere near
as slick and user friendly as the PHP.net system.

One other thing I seen on the PHP.net docs is it''s got alot of
introduction pages, in addition to the functional reference.

Jeremy, you up for working together to join forces and architect the
best doc system in the universe? :)

Nathaniel.

On 1/4/07, Jeremy Durham
<rails-mailing-list-ARtvInVfO7ksV2N9l4h3zg@public.gmane.org>
wrote:
>
> 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
>
> --
> Posted via http://www.ruby-forum.com/.
>
> >
>

-- 
Nathaniel Steven Henry Brown

Toll Free: 1-877-446-4647
Vancouver: 604-724-6624

http://inimit.com

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

I''ve been in correspondence with Courtenay about the caboo.se project.
I''m
happy to sign up and spend some time on this because it will be of so much
benefit to so many people. My reluctance (and possibly a concern of others)
relates to working on Yet Another Rails Documentation project. As has been
noted in this thread, a great deal of good information *exists*, but it is
not coalesced in one single location.

If we were able to settle on a single project and put all the
community''s
weight behind that, it would be more likely to succeed. Because of the
support the caboo.se project has received thus far, they might be a logical
choice.

So, here''s my vote: Let''s nominate the caboo.se project as the
"official"
Rails documentation project!

Anyone care to second that?

Steve




A concept I just came up with which may work really well is to have a
user/member only wiki with open comments.

So anyone can create an account for the wiki (with email verified) and
once they have, they can create new pages. Once the page has been
created, users can submit comments to the page similar to the PHP.net.

It would be a combo of a wiki with comments.

I really like the setup railsmanual.org has which I maintain that is
based on the Rannotate RDOC enhancements, but it''s still nowhere near
as slick and user friendly as the PHP.net system.

One other thing I seen on the PHP.net docs is it''s got alot of
introduction pages, in addition to the functional reference.

Jeremy, you up for working together to join forces and architect the
best doc system in the universe? :)

Nathaniel.


-- 
View this message in context:
http://www.nabble.com/-Rails--Rails-API-Documentation-tf2908363.html#a8172786
Sent from the RubyOnRails Users mailing list archive at Nabble.com.


--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

s.ross wrote:
> I''ve been in correspondence with Courtenay about the caboo.se
project. I''m
> happy to sign up and spend some time on this because it will be of so much
> benefit to so many people. My reluctance (and possibly a concern of others)
> relates to working on Yet Another Rails Documentation project. As has been
> noted in this thread, a great deal of good information *exists*, but it is
> not coalesced in one single location.
> 
> If we were able to settle on a single project and put all the
community''s
> weight behind that, it would be more likely to succeed. Because of the
> support the caboo.se project has received thus far, they might be a logical
> choice.
> 
> So, here''s my vote: Let''s nominate the caboo.se project
as the "official"
> Rails documentation project!
> 
> Anyone care to second that?
I agree that it would be nice if there was just one API/documentation 
project everybody was contributing too. However caboo.se isn''t working 
for me. E.g. type in "paginator" or "pagination" as a search
in caboo.se
and compare that with what you get back in railsmanual.org.

--
Michael Wang

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

I think searchability and presentation are issues, but I don''t agree
that the
*current* state of any of these implementations is how they will stabilize.
If you go to railsmanual.org, you will get stray hits and no
characterization of the information you will find when you receive your list
of links to "paginator" or "pagination".

My belief is that if the Rails community throws its support behind one
option, people will do what it takes to make that option reflective of the
overall quality of the framework. At least, that''s my hope. So, in my
mind,
the real challenge to the community is to make a decision (among a
significant number of people) and then support it.

Steve



Michael Wang-5 wrote:
> 
> 
> s.ross wrote:
>> I''ve been in correspondence with Courtenay about the caboo.se
project.
>> I''m
>> happy to sign up and spend some time on this because it will be of so
>> much
>> benefit to so many people. My reluctance (and possibly a concern of
>> others)
>> relates to working on Yet Another Rails Documentation project. As has
>> been
>> noted in this thread, a great deal of good information *exists*, but it
>> is
>> not coalesced in one single location.
>> 
>> If we were able to settle on a single project and put all the
community''s
>> weight behind that, it would be more likely to succeed. Because of the
>> support the caboo.se project has received thus far, they might be a
>> logical
>> choice.
>> 
>> So, here''s my vote: Let''s nominate the caboo.se
project as the "official"
>> Rails documentation project!
>> 
>> Anyone care to second that?
> 
> I agree that it would be nice if there was just one API/documentation 
> project everybody was contributing too. However caboo.se isn''t
working
> for me. E.g. type in "paginator" or "pagination" as a
search in caboo.se
> and compare that with what you get back in railsmanual.org.
> 
> --
> Michael Wang
> 
> 
-- 
View this message in context:
http://www.nabble.com/-Rails--Rails-API-Documentation-tf2908363.html#a8183428
Sent from the RubyOnRails Users mailing list archive at Nabble.com.


--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Hi guys,
I''d like to clarify a few things, and ask for help.

Firstly, the railsmanual site just draws from the rdoc source code,
which is to say, the comments embedded within the Rails source.  So the
interface or searching thereof is open to much interpretation.

That being said, the "caboose documentation" is not about the
presentation of the API, or its searchability, but rather, the raw
information within.  The documentation hosted on caboo.se is actually
not part of this; it''s a special version of the docs with a lot of
exposed private methods, for advanced developers to use as a reference.

The "caboose documentation project" is a fund that has been set up to
provide cash for well-written Rails documentation, as an incentive.
There are a few steps to this project, and we''ve been gathering ideas
on a wiki http://caboose.stikipad.com/documentation.  Basically, it can
be summarized like

- better API docs, in-code comments
- more examples
- recipes, or task-oriented guides with links into the API

Currently, we are working on an application that makes it easy to
modify and annotate as you browse the API, thereby making it easier for
everyone to contribute to improving the docs.  We''re aiming to have it
automatically post to the official Trac, so that rails-core can
integrate documentation fixes easily. If you can help with this let me
know, we''re unable to get it working right now.

I''ve created a google-group for the doc project, so you can take your
ideas there.
http://groups-beta.google.com/group/rubyonrails-documentation

Ideally, as you find documentation that is lacking, or have an idea
where more examples or fixup is required, post to that group, and we
can assign it to someone to write.

We would greatly appreciate everyone''s input!

Courtenay
caboo.se


On Jan 5, 10:39 am, "s.ross"
<cwdi...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> I think searchability and presentation are issues, but I don''t
agree that the
> *current* state of any of these implementations is how they will stabilize.
> If you go to railsmanual.org, you will get stray hits and no
> characterization of the information you will find when you receive your
list
> of links to "paginator" or "pagination".
>
> My belief is that if the Rails community throws its support behind one
> option, people will do what it takes to make that option reflective of the
> overall quality of the framework. At least, that''s my hope. So, in
my mind,
> the real challenge to the community is to make a decision (among a
> significant number of people) and then support it.
>
> Steve
>
>
>
> Michael Wang-5 wrote:
>
> > s.ross wrote:
> >> I''ve been in correspondence with Courtenay about the
caboo.se project.
> >> I''m
> >> happy to sign up and spend some time on this because it will be of
so
> >> much
> >> benefit to so many people. My reluctance (and possibly a concern
of
> >> others)
> >> relates to working on Yet Another RailsDocumentationproject. As
has
> >> been
> >> noted in this thread, a great deal of good information *exists*,
but it
> >> is
> >> not coalesced in one single location.
>
> >> If we were able to settle on a single project and put all the
community''s
> >> weight behind that, it would be more likely to succeed. Because of
the
> >> support the caboo.se project has received thus far, they might be
a
> >> logical
> >> choice.
>
> >> So, here''s my vote: Let''s nominate the caboo.se
project as the "official"
> >> Railsdocumentationproject!
>
> >> Anyone care to second that?
>
> > I agree that it would be nice if there was just one API/documentation
> > project everybody was contributing too. However caboo.se
isn''t working
> > for me. E.g. type in "paginator" or "pagination"
as a search in caboo.se
> > and compare that with what you get back in railsmanual.org.
>
> > --
> > Michael Wang--
> View this message in
context:http://www.nabble.com/-Rails--Rails-API-Documentation-tf2908363.html#...
> Sent from the RubyOnRails Users mailing list archive at Nabble.com.

--~--~---------~--~----~------------~-------~--~----~
 You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk-unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---