On Dec 14, 2007, at 8:28 AM, Pratik wrote:
> I have always felt that rails api docs are not as bad as people make > it sound like. We're not writing a manual for a microwave that doesn't change after someone decides on the specs and thinks about the user interface, this is documentation for a constantly evolving framework. I think we should keep the documentation close to the source and preferably in the source where you're constantly reminded that any patch should also mean an update to the surrounding documentation. For external documentation you need either intimate knowledge of way the source works, or use the current API docs as a source. That sounds like a maintenance hell to me. Higher level documentation could be sustainable because it would only describe concepts, and not implementation details (.ie an explanation what ActiveRecord is and what problems it solves.) Higher level documentation is mostly useful for newcomers and they like to dive in headfirst, not spend a whole day reading about architecture. Long story short: good API docs, good examples, screencasts, blog posts and a forum/mailinglist seem like the way to go and I think we're already pretty well supplied in those areas. Manfred --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
