AR Query Interface: standardize examples to use the same models

[ashley e]

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.

1. 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.

2. 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?

[Ryan Bigg]

I think this is a great idea and will make this guide easier to read. Please submit a patch or two for this!

--
You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
To unsubscribe from this group and stop receiving emails from it, send an email to rubyonrails-do...@googlegroups.com.
To post to this group, send email to rubyonra...@googlegroups.com.
Visit this group at https://groups.google.com/group/rubyonrails-docs.
For more options, visit https://groups.google.com/d/optout.

[ashley e]

I'll create an issue on github and then have a PR there before long.

On Friday, January 11, 2019 at 7:56:06 AM UTC-8, Ryan Bigg wrote:

I think this is a great idea and will make this guide easier to read. Please submit a patch or two for this!

 

On 6 Jan 2019, 09:17 +1100, ashley e <ash...@ashleycaroline.com>, wrote:

The ActiveRecord Query Interface guide starts off by saying:

  Code examples throughout this guide will refer to one or more of the following models:  

[snip]

[ashley e]

Ryan -- I've submitted a PR but haven't seen much feedback on it.  

I asked one of my associates to review it and he did.  But I still have some general questions about it for 'official' Rails document folks.

Reviewing that PR is a lot of work, I know.  But I think it can become the basis for examples for the other basic ActiveRecord guides.

Looks like documentation PRs do not get automatically assigned to anyone.

Should I just hang tight for a while and wait a bit more?  Or is there a way I can encourage some more feedback?

[Vipul A M]

Hi Ashley, I did take a look at it. As you mentioned its a long PR, it will take some time to review it. 

Whoever from the the Rails team is free next time will take a look at it.

Thanks for your work and for being patient!

[ashley e]

Thanks for the quick reply, Vipul.

And thanks for letting me know it'll happen.  Understanding the expectations makes it easy to wait. :-)