The ActiveRecord Query Interface guide starts off by saying:
Code examples throughout this guide will refer to one or more of the following models:
… **Client, Address, Order, and Role models. **
But the guide also uses other models in examples. Users, Invoices, Authors, Books Persons and more are used in examples. And section 12. Joining Tables specifically introduces yet another group of models: Category, Article, Tag, Guest, and Comment
It is valuable and important to stick with one group of models throughout the guide because then readers can focus on learning about querying ActiveRecords (the actual topic), and not also spend cognitive time learning and becoming familiar with different groups of models. That additional complexity can seem trivial to someone already comfortable with ActiveRecords, etc., but that complexity for new learners is an additional burden that shouldn’t be discounted.
-
Can we change the examples in the guide to use just one group of models? (Client, Address, Order, and Role) If not that group of models, then some other single group that is rich enough to so that they can be used for the examples.
-
Can we also provide information on the attributes included in those models so that new learners have a more complete picture of them when they start reading the guide? (They could use that information, for example, to create those models in their own system to work with the examples.)
This could be done as a link to another page with the details for each of the models.
(I think it’d be even better to have the same group of models used throughout the all of the Models, Views, and Controllers guides. But it makes sense to start with one guide and then later tackle the others.)
Thoughts?
