From a new Rails user (copied from the mailing list):
I’m having a hard time figuring out how to build my application using Rails. As i go along, simple questions occur to me like: are you supposed to have a separate model class (each in its own file, in the app/models directory) for each table in your database? You’d think that something as basic as this would be laid out in the introductory documentation but, alas, the tutorials seem to mostly cover getting your system set up and the rails documentation all reads like reference manuals (which is what they are). I’m feeling a big lack of anything in the middle that explains the basic methodology to be used in building models and controllers for anything but the most trivial examples.
This sentiment is fairly common among people trying to grok the framework. One good way to address it is to add manuals on the Manuals page. Another is to add common use cases as Howtos. A third would be to create some “big picture” or “across the grain” documents that new users could use to orient themselves (e.g. tracing the life story of a request as it goes through the rewriting/routing process until it hits the method on the controller). Fourth, the APIs are fairly well documented, but it’s always possible to improve.
And finally, linking all these together so that people on one track can cross over in a meaningful way. The process of groking something involves asking a deeply nested hierarchy of “When?” “Where?” “Why?” “What?” “How do I…?” and “How does it..?” questions as you explore the knowledge network.
LeeO: It’s nice to see others interested in improving the docs. Please see, and contribute to DocumentationDiscussion for more on the matter.