What I'm mostly concerned with is what I stated in my last message. Why would someone invest a considerable effort for creating a superb documentation do ActionController::Base#render if some core members won't show any respect for them by removing the docs while refactoring the code base? That is the most frustrating experience. I'm not inclined to spend time fixing documentation if the core members don't care enough about it and won't hesitate in removing it when it seems appropriate to them.It could be an overlook, in the Rails 3 days refactors were really wild.
git log -S "Rendering an action"
commit 19c3495a671c364e0dc76c276efbcd9dc6914c74
Author: Yehuda Katz + Carl Lerche
rm -r controller/base!
And suddenly lots of useful documentation written with care just went away. This means only testing matters. As long as tests pass go for it. I didn’t generalize. I always said “some of the rails core developers”. But the effect is the same. A single developer working this way will suffice to remove useful documentation. I certainly don’t agree. I used to do web development in Perl before I started with Rails in 2007. I wasn’t doing web development for some years at that time having spent the last years working with real-time stuff with C and C++ on Xenomai and Kernel modules developing. When I changed my job in 2007 I would be back to web development and decided to look for recent web frameworks as I wasn’t much satisfied with the state of Perl. So I evaluated lots of them, like TurboGears, Django, J2EE, MS Dot Net and a few other options and Rails became my choice, specially because it was very well documented. I guess it was about version 1.0 or 1.1 at that time. One of my selling points when trying to convince others to move to Rails was its very well documented API, full with great examples. This wasn’t certainly the norm in the Perl community or any other I’ve searched at that time. The only drawback I saw in Rails by that time was the lack of internationalization support, but at the end I decided for Rails instead of TurboGears, my second option. I didn’t know Ruby or Python by that time, so I didn’t care much about the language, but the Rails migrations tool was the key point for my choice by that time. And I’m happy I opted for it. Rails wasn’t the only well documented Ruby gem. I found in the Ruby community a great experience with regards to documentation that I haven’t found in other communities. I’ve been doing mostly Java and Groovy (Grails) development since 2009 when I changed my job. And their documentation was really bad. I managed to convince them a while ago to adopt the docrails model for their User’s Guide, which is a separate project, and the documentation has gotten much better in the last months. But their Java API are in really bad shape as most Java API I’ve been working with. After that I changed my job again last year, but my new company wanted me to maintain another Grails application. Due to some recent Grails critical bug that I’ve reported a few months ago and that is still unfixed, I decided to create a new Rails application and proxy the affected requests to it. This happened about one or two months ago. Since then I’m back to Ruby and Rails development and I can clearly see the difference with regards to Rails documentation from 2007 to 2009 and the current situation and they’re a totally different experience. Now I’m working mostly with Rails again, porting the old application to the newest one written with Rails in chunks. So I’m re-getting familiar with the current state of Ruby gems and Rails again. Here is my experience with great documentation I’ve found so far: Sequel, my ORM of choice: RSpec, my Ruby testing tool of choice: Factory Girl, my object factory of choice: Draper (I replaced it recently with SimpleDelegator, but it still has great documentation): Konacha (I replaced it with my own rails_sandbox_jasmine gem, but it is still a great example of good documentation): jquery-ui-themes: Devise: eco: spork: Capybara: - finders: Passenger: Ruby-core: Besides Ruby gems, other JavaScript libraries that are very well documented: jQuery: jQuery UI: jqTree: jQuery form: Jasmine: Jasmine-jQuery: Sinon.js: jQuery-noty: (tons of well organized examples) As you can see, all libraries I’m currently using are pretty well documentation, because this is very important to me. I just opted for Rails in 2007 because it used to have a superb well documented API and guides. While the guides are still excellent and getting better and better, the same can’t be said of the API documentation itself. It used to be great in Rails 1, but it is not in Rails 3. I agree that changing the main page is a required change now that Rails needs some more organized API since it is more modular, which is great. But while a great job was done in the code base during the Rails 3 refactoring, not enough care was driven to the documentation and then lots of great resources were just trashed at no absolute reason. And that is the sad thing. I don’t really intend to invest a considerable amount of time working on documentation improvements for Rails unless all core team members take documentation as serious as they take testing. My time is limited and I always try to make better use of it. Currently I’ve been focused on some testing effort for JavaScript: Here are some repositories I’ve been working with in the last days: There are other projects I’ve been involved with in the last weeks as well, like Sequel and jqTree. My previous experience trying to contribute to Rails and Gitorious in the past have been so bad that I’ll hardly consider contributing to those projects, since they usually consume a lot of my little free time for so little result. Usually I’ll prefer to use my time to work on those other projects. I do even intend to write an article on good practices about client-side code testing writing later after I take a nap. So, there are so many projects I’d like to work on and so little free time that I’ll hardly opt for working in a task that some people of the core team don’t seem to see as much value as I do. I hope you can understand my point. Best, Rodrigo.
