Hi All Just a few minutes back I came across a post about autotest/zentest and that post reignited the feeling I get when I look at RDoc, RoR documentation. The main thing that is lacking in RoR and to some extent Ruby''s RDoc is showing method names in HTML is not documentation. The arguments to method, exception/errors raised by method, return value and a usage example completes the documentation. I understand that RoR is still young and even Java didn''t catch with good documentation for till 1999-2000. But we don''t have to wait as long as Java or .Net did, we can learn from the cycle these languages or vendors went through. For Ruby and RoR''s corporate level adoption its pertinent that enough time is devoted to documentation. Towards this goal I would like everybody to come forward and share their ideas and experiences towards improving the documentation. Afterall we can''t just be complaining all the time, its open source for a reason. So everybody please come forward and contribute to this thread and help RoR getting rid of the documentation problem -daya -------------- next part -------------- An HTML attachment was scrubbed... URL: http://wrath.rubyonrails.org/pipermail/rails/attachments/20060811/09284a94/attachment.html
support the cause: http://blog.caboo.se/articles/2006/08/04/the-caboose-rails-documentation-project $15k and counting... On 8/11/06, linux user <fanoflinux@gmail.com> wrote:> > Hi All > > Just a few minutes back I came across a post about autotest/zentest and > that post reignited the feeling I get when I look at RDoc, RoR > documentation. > > The main thing that is lacking in RoR and to some extent Ruby''s RDoc is > showing method names in HTML is not documentation. The arguments to method, > exception/errors raised by method, return value and a usage example > completes the documentation. > > I understand that RoR is still young and even Java didn''t catch with good > documentation for till 1999-2000. But we don''t have to wait as long as Java > or .Net did, we can learn from the cycle these languages or vendors went > through. > > For Ruby and RoR''s corporate level adoption its pertinent that enough > time is devoted to documentation. Towards this goal I would like everybody > to come forward and share their ideas and experiences towards improving the > documentation. Afterall we can''t just be complaining all the time, its open > source for a reason. > > So everybody please come forward and contribute to this thread and help > RoR getting rid of the documentation problem > > -daya > > _______________________________________________ > Rails mailing list > Rails@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails > > >-------------- next part -------------- An HTML attachment was scrubbed... URL: http://wrath.rubyonrails.org/pipermail/rails/attachments/20060811/f1a1b9b9/attachment.html
I bet someone will have already answered with this link, because gmail seems to be lagging in deliveries, but in an effort to answer the call, I am giving it a try! If you want to help with the documentation of Rails, then support the Rails Documentation Drive: http://blog.caboo.se/pages/documentation_drive I would like to see better documentation of what the arguments to most of the methods are, especially the options arguments. How do I discover what the valid options are for a method when that method has 5 layers of abstraction? Anyway. Support the Documentation Drive!! Carl On 8/11/06, linux user <fanoflinux@gmail.com> wrote:> > Hi All > > Just a few minutes back I came across a post about autotest/zentest and that > post reignited the feeling I get when I look at RDoc, RoR documentation. > > The main thing that is lacking in RoR and to some extent Ruby''s RDoc is > showing method names in HTML is not documentation. The arguments to method, > exception/errors raised by method, return value and a usage example > completes the documentation. > > I understand that RoR is still young and even Java didn''t catch with good > documentation for till 1999-2000. But we don''t have to wait as long as Java > or .Net did, we can learn from the cycle these languages or vendors went > through. > > > For Ruby and RoR''s corporate level adoption its pertinent that enough time > is devoted to documentation. Towards this goal I would like everybody to > come forward and share their ideas and experiences towards improving the > documentation. Afterall we can''t just be complaining all the time, its open > source for a reason. > > So everybody please come forward and contribute to this thread and help RoR > getting rid of the documentation problem > > -daya > _______________________________________________ > Rails mailing list > Rails@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails > > >
dave davidson
2006-Aug-14 13:47 UTC
[Rails] Re: Rails Documentation is RoR''s achilles heel
Carl Fyffe <carl.fyffe@...> writes:> If you want to help with the documentation of Rails, then support the > Rails Documentation Drive: > http://blog.caboo.se/pages/documentation_driveGreatest. Fundraiser. Ever.