I've started a documentation effort of my own back in June, I've got the docs up on a Github repository: http://github.com/radar/how-rails-works. Currently it covers only timezones and respond_to for Rails 2.3. There was another guy who was going to do Dynamic Finders but he hasn't contributed to that recently. I like the idea of version specific documentation. Perhaps we could get the docrails team to volunteer for this kind of effort?
2009/9/13 Yehuda Katz <[email protected]> > Carl and I are planning on spending some time on internals documentation > once we ship an alpha (for plugin authors). > If you have a specific requests for documentation (especially in > ActionPack), feel free to email me and I'll add it to the list of priorities > for when we do documentation. > > -- Yehuda > > > On Sat, Sep 12, 2009 at 10:51 AM, Czarek <[email protected]>wrote: > >> >> On Sat, Sep 12, 2009 at 06:39:34AM -0700, Rodrigo Rosenfeld Rosas wrote: >> > >> > This makes it very hard to get new contributors to Rails core since it >> > seems every railer is busy and chances are small that they have enough >> > time to figure out the Rails internals by themselves so that they can >> > contribute small changes. There are a lot of plugin contributions >> > since its documentation is well written. I think there could be more >> > contributors if we had a README.internals that explained the whole >> > idea about how Rails is structured and the reasons behind it. Then, >> > each major update to Rails internal structure could be reflected in >> > this document... >> >> Same problem here, but ... >> >> There are articles about the internals around the net. Unfortunately >> they quickly get outdated. And in a way, this is a good thing, because >> it means Rails is continuously evolving. >> >> With all the changes going in to 3.0, maintaining such documentation >> may be a nightmare, unless it becomes version specific. Especially >> with all the refactoring going on. >> >> Here are a few tips I found useful: >> >> 1) logging - insert logging everywhere you can when solving a problem. >> With very concise code this helps understand what is going on and when >> faster than any documentation. >> >> 2) reading changelogs - sometimes unrelated stuff can give insight >> into the peculiar cases that Rails has to handle. >> >> 3) debugger - stopping and looking at the backtrack can teach a lot >> about the architecture. >> >> 4) Lighthouse - like reading changelogs, but with more details >> >> 5) browsing through the source when you don't need to - when you are >> less frustrated and you don't need to urgently find out what's wrong. >> >> Especially the last part - hack on ruby when you are not under >> pressure. Do it for fun. Learn things before you need them. Read >> articles about ROR when you have spare time. It pays off eventually. >> Even if this would mean investing more time in total, it will be more >> pleasurable. >> > >> > I was just trying to add a :full_message parameter to validations, so >> > that I could prepare a patch to LightHouse, but was stuck trying to >> > figure out how ActiveRecord is loaded, how Validations are included in >> > ActiveRecord without being required (when I discovered they are >> > autoloaded), what are the differences between ActiveModel and >> > ActiveRecord and several other doubts. It would be much easier if such >> > a README.internals document exists. I spent about 2 hours doing really >> > nothing useful to Rails itself, while I could use this time to >> > actually write a useful patch... >> >> I know what it is like to wake up after a few hours of hacking knowing >> you basically did ... nothing really. >> >> > I would like to know what is the Rails core team opinion about that. >> >> Beware - my opinion is just from a user struggling to understand >> Rails, not anyone from the core team. >> >> Cheers >> >> -- >> Cezary Bagiński >> >> >> > > > -- > Yehuda Katz > Developer | Engine Yard > (ph) 718.877.1325 > > > > -- Ryan Bigg --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Ruby on Rails: Core" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/rubyonrails-core?hl=en -~----------~----~----~----~------~----~------~--~---
