Comments on: The state of Ruby on Rails documentation http://izumi.plan99.net/blog/index.php/2008/07/19/the-state-of-ruby-on-rails-documentation/ Ecchi nanowa ikenai to omoimasu Tue, 03 Jan 2012 16:14:50 +0000 hourly 1 http://wordpress.org/?v=3.3.1 By: Robin2 http://izumi.plan99.net/blog/index.php/2008/07/19/the-state-of-ruby-on-rails-documentation/comment-page-1/#comment-9328 Robin2 Mon, 21 Jul 2008 07:03:23 +0000 http://izumi.plan99.net/blog/index.php/2008/07/19/the-state-of-ruby-on-rails-documentation/#comment-9328 There must be lots of people like me who would prefer if somebody was paid to write documentation in a useful discursive style with lots of examples. I don't know enough to contribute to the documentation. I have a number of Rails books but (just like books on ASP.net etc) they cannot cover all of the fine details. And it can be very frustrating when something won't work, but the documentation is not sufficient to explain the point. I've come across several cases where there is a variety of ways to use a function, but there is only an example for one way, and often the books use he same examples as the online documentation. Another thing that appears nowhere in the documentation is an explanation of why features have been included - for example "The purpose of this method is to enable you to do XXX." That sort of comment would quickly allow a newcomer to decide that this is / is not / the method that is relevant for his /her purposes. There must be lots of people like me who would prefer if somebody was paid to write documentation in a useful discursive style with lots of examples.

I don’t know enough to contribute to the documentation.

I have a number of Rails books but (just like books on ASP.net etc) they cannot cover all of the fine details. And it can be very frustrating when something won’t work, but the documentation is not sufficient to explain the point. I’ve come across several cases where there is a variety of ways to use a function, but there is only an example for one way, and often the books use he same examples as the online documentation.

Another thing that appears nowhere in the documentation is an explanation of why features have been included – for example “The purpose of this method is to enable you to do XXX.” That sort of comment would quickly allow a newcomer to decide that this is / is not / the method that is relevant for his /her purposes.

]]> By: Documentação para Ruby on Rails | development.log http://izumi.plan99.net/blog/index.php/2008/07/19/the-state-of-ruby-on-rails-documentation/comment-page-1/#comment-9321 Documentação para Ruby on Rails | development.log Sun, 20 Jul 2008 14:26:04 +0000 http://izumi.plan99.net/blog/index.php/2008/07/19/the-state-of-ruby-on-rails-documentation/#comment-9321 [...] também a opinião do Hongli Lai (da Phusion) e do TheWebFellas sobre o [...] [...] também a opinião do Hongli Lai (da Phusion) e do TheWebFellas sobre o [...]

]]>