AR Query Interface: standardize examples to use the same models

19 views
Skip to first unread message

ashley e

unread,
Jan 5, 2019, 5:17:05 PM1/5/19
to Ruby on Rails: Documentation
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

unread,
Jan 11, 2019, 10:56:06 AM1/11/19
to rubyonra...@googlegroups.com
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

unread,
Jan 17, 2019, 11:24:21 AM1/17/19
to Ruby on Rails: Documentation
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

unread,
Jan 27, 2019, 2:55:41 AM1/27/19
to Ruby on Rails: Documentation
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

unread,
Jan 27, 2019, 3:53:24 AM1/27/19
to rubyonra...@googlegroups.com
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

unread,
Jan 27, 2019, 7:32:16 PM1/27/19
to Ruby on Rails: Documentation
Thanks for the quick reply, Vipul.

And thanks for letting me know it'll happen.  Understanding the expectations makes it easy to wait. :-) 
Reply all
Reply to author
Forward
0 new messages