Comments (15)
Current chapters:
- Passing in Arguments
- Using Conditionals
- Applying a Default Scope
- Merging of Scopes
- Removing All Scoping
from rails.
Hi great initiative, about the:
- Identifying any missing sections that could enhance the guide's completeness
I would love more info on queryingpolymorphic relationships
since there is one mention of it the docs and in association_basics there is no query example in it.
from rails.
I took a quick look at stackoverflow researching by the terms activerecord and ruby on rails in most frequent tab. The first question is about case-insensitive search in rails model an example of something with could more explicit in docs.
https://stackoverflow.com/questions/tagged/activerecord%2bruby-on-rails?tab=Frequent
I believe that stackoverflow would be useful for this kind of research.
from rails.
I would second the comment about changing the order of the chapters. Maybe a consistent example that progresses through the chapters would be helpful?
A quick example regarding the chapters, maybe moving pluck
up towards the top. I find that to be used pretty frequently in relatively simple use cases. I can see beginners thinking "how do I just get the :id of a record?" for example.
Some chapters could probably use some more examples and/or clarity. JOINS
and INCLUDES
for example. Joins currently only has examples for a single association. Maybe add an example with nested associations?
This is a big effort. I'm happy to help contribute.
from rails.
Hey @Ridhwana ,
Wow this is a long piece of (much needed) guide documentation. I have some feedback based on how I try and structure the technical copy at AppSignal. This feedback is mostly related to the structure of the copy rather than the structure of the documentation.
Hi @noccor thanks for your thoughts on the structure of the copy. We were specifically posting to request information about the structure of topics, but it never hurts to hear feedback about the copy, too, or processes that other technical writers follow.
@Ridhwana and @bhumi1102 have been working on updating the guides since early February (Guides that have been merged), so I think you'll be pleased to see that they follow a similar approach with their own technical writing. In particular you can see all of your advice reflected in the Active Model Basics Guide which Ridhwana recently worked on.
This level of feedback would be really appreciated once the writers have edited each guide and pushed their PRs to GitHub for community review, so we would love it if you could keep an eye out for those. We have approximately 1-2 a week up for review.
Thanks!
from rails.
No problem @AmandaPerino, thanks for your response. I'll keep an eye out for up-coming PRs where this feedback is more valuable/well placed.
I'd say my only current structure feedback at this point is based on the order of the example models where I'd flip the ordering so the schema comes before the models.
It's definitely impressive work from @Ridhwana and @bhumi1102 - look forward to following future PRs!
from rails.
I would ask who's target audience. Are we trying to improve documentation for the beginners or advanced users?
@AmandaPerino
from rails.
I would ask who's target audience. Are we trying to improve documentation for the beginners or advanced users? @AmandaPerino
That's a great question @biske. These guides are meant to be more for beginners/mid-level.
Writing aimed at beginners (with more context) will not put off a more experienced developer, so essentially it will serve both audiences. It is further likely that the more advanced user would head straight to the API docs first anyway.
We are hoping that beginners will come to these guides searching for an answer (and find it), but also discover a load of other possibilities on how Active Record (in this example) can be utilized.
from rails.
I don't have a strong opinion on this, but maybe it would be good to change the order of the chapters. Kind of like going up in level of complexity a little at a time and by level of importance or by the most frequent things first. For example, scopes or enums are way down and are things that are used quite a bit. Likewise, selecting specific fields, unscope, I don't feel like it's something that a beginner would use to present it so early on. I don't want it to be misunderstood in the sense that this shouldn't be. I'm just saying that maybe the order in which it's taught can be quite influential in a junior developer being able to understand things more quickly.
from rails.
Hi, I love this effort! In the guide, I sometimes miss a brief mention of async queries and calculations, possibly also its strengths and limits.
from rails.
maybe a subquery section close to the join section.
from rails.
Hey @Ridhwana ,
Wow this is a long piece of (much needed) guide documentation. I have some feedback based on how I try and structure the technical copy at AppSignal. This feedback is mostly related to the structure of the copy rather than the structure of the documentation.
As the guide is quite long, and this is not a PR I thought I'd put some focus here and try and keep my as feedback brief as possible. Please let me know if anything I say is unclear!
1. Explain the aim of documentation in the intro
In the section 1 What is the Active Record Query Interface? I'd say there is no harm in re-asserting the aim of the document:
"This guide will give you a deeper understanding of the Active Record Query Interface, introducing the core concepts and methods needed to efficiently manage Active Record queries."
Of course, there is a "this guide will help you" section at the top of the page, but adding a sentence or two outlining the guide's intent will help further clarify the guide, make the focus clear, and catch the attention of people who may scroll past the bullet list at the top of the page.
2. Model introduction:
Regarding the introduction to example models in the section 1 What is the Active Record Query Interface?, I would recommend putting this content in its own sub-section (ie "Example models") and having the following structure:
- Brief explanation of the example app: "In this guide, we'll use a book store app as an example..."
- The diagram of the
db_schema
(consider adding created_at, updated_at columns to the models to make it more explicit) - The example model code blocks
Also note: With domain-specific terms like ISBN
, I'd recommend explaining quickly what this is/stands for, so in the event, a reader is uncertain they don't have to leave the guide for more context.
3. Descriptive tone of voice and accessible language
Using the section Retrieving Objects from the Database as an example, when describing an action, I always favour a descriptive tone of voice (using the ing form of verbs). I'd also advise using more accessible language. For example, terms like "fire a query" or "Instantiate a class" may not be clear to all English speakers, we can use words like "create" and "execute" instead:
- Converting the supplied options to an equivalent SQL query.
- Executing the SQL query and retrieving the corresponding results from the database.
- Creating the equivalent Ruby object of the appropriate model for every resulting row.
- Running
after_find
and thenafter_initialize
callbacks, if any.
4. Describe concepts before demonstrating them
It can be beneficial to quickly explain what something is before demonstrating it. For example, in the 3.4 NOT Conditions section, a short explanation could be added before the example:
A
not
condition fetches records that do not match your Active Record query, for example when trying to find customers that do not have anorder_count
of 1, 3 or 5...
Another example is with N+1 queries problem, where it may be beneficial to explain what an N+1 query is before walking a reader through an example of one.
This helps keep the docs explicit and scannable and provides greater context to lesser senior developers before introducing them to code samples.
5. Lists that link
When a list is listing concepts the documentation describes, make that list item link to the relevant docs section to avoid the reader having to scroll down toward it.
Final tiny nit-pick: In Retrieving Multiple Objects in Batches it says "as" when I think it is meant to say "such as".
from rails.
@Ridhwana @AmandaPerino Excellent idea!
Back in 2020, there was the May of WTFs, where a lot of great feedback was given. Some of it pertains to Active Record and documentation.
https://discuss.rubyonrails.org/c/a-may-of-wtfs
Do you happen to know if anyone has gone through those threads to see if any of the action items from those pertain to this project as well?
from rails.
13.1.1 Solution to N + 1 Queries Problem
Active Record lets you specify in advance all the associations that are going to be loaded.
The methods are:
[includes](https://api.rubyonrails.org/v7.1.3.2/classes/ActiveRecord/QueryMethods.html#method-i-includes) [preload](https://api.rubyonrails.org/v7.1.3.2/classes/ActiveRecord/QueryMethods.html#method-i-preload) [eager_load](https://api.rubyonrails.org/v7.1.3.2/classes/ActiveRecord/QueryMethods.html#method-i-eager_load)
Some added guidance on when to use each of the three condensed down in single place would be helpful. I also think join
should be included in this discussion as well. Selfishly these are the kinda of things I personal use the guides for in my day-to-day, but I'm guessing others would find this useful as well.
Thank you for your work on this.
from rails.
I notice that neither the "Pure string conditions" section, nor the linked security guide mention Arel.sql which I believe is still the required method for more complex pure sql conditions. If this is indeed still the recommended approach, I think it deserves a mention in one of these two documents. Thanks!!!
from rails.
Related Issues (20)
- in guides.rubyonrails documentation of threads: missing info about db access HOT 1
- HasMany/HasOne associations: combining `:through` and a scope including a `.merge` leads to missing table HOT 1
- [Question] Why doesn't set_pk_sequence! support the parameter for is_called? HOT 5
- Rails 6.0.6.1 transaction rollback doesn't reload object HOT 1
- Error `undefined method `start_with?' for nil` when logging
- new_framework_defaults initializer for Rails 7.1 not setting ActiveRecord.run_after_transaction_callbacks_in_order_defined
- [Feature Request][CSP] Support for multiple Content Security Policies HOT 2
- ActionCable: Invalid channel causes repeated subscription attempts
- Code generation memory bloat post alias fix HOT 8
- Rails throws an error when sending invalid UTF-8 query param HOT 1
- Lazy default_scope evaluation in joined models loses original context
- Some Rails integration tests break with rack 3.1 HOT 4
- ActionText Editor Previews uploaded pre 7.1.3.4 are broken in 7.1.3.4 after a resave HOT 9
- Inversion of associations with :through don't work until it's saved
- Incorrect `has_many through` load with custom association name and custom keys type
- Demo video on home page doesn't work as demo'd HOT 1
- Infinite loop passing form_builder in partial as local after update to 7.1.3.4 (was 7.0.8.4) HOT 11
- [ActiveRecord] alias_attribute does not work on methods defined in the superclass HOT 3
- Actionview: ArgumentError "Invalid formats" exception with empty invalid_values when additional format gets added after update to Rails 7.1.3.4 HOT 1
- Add a dummy encryption key for ActiveRecord::Encryption
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from rails.