On Aug 1, 2006, at 1:34 PM, Michael Genereux wrote:
Are all new, noncritical patches on hold for right now pending the new ticket page? I've started editing documentation in the core Rails classes to make them more clear, fix typos, and in some cases, fill in undocumented public methods. Speaking of which, is this what David wanted at RailsConf when he asked for more documentation? I interpreted as such and then, after I'd done some work, I realized he may have meant the HOWTOs in the wiki. Can someone on the core team give me clarity on what they would have a warm body do if they had them once a week for eight hours?
I'd like to see the docs thoroughly reviewed against the source and expanded with concise examples from the wiki et al. Think of the process as rcov for docs - the behavior of a method should be transparently and completely reflected in its docs. See AR associations for some poor examples (Dave T ran into considerable ambiguity documenting them for agile2.)
Interestingly, something that'd make documentation easier and clearer would be more managable unit tests. Since a method's tests are our ultimate measure of its expected behavior, good documentation starts there. Tests are roughly organized but a jumble when it comes to "where is method X behavior tested?". Break em up those ice floes and reorganize similarly to Active Support's lib layout.
Thanks Michael - jeremy _______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
