"Reading docs top to bottom" is the answer to this frustration. It's strange that people don't think this is something they should do.
People would often ask how I knew so much about rails and, ya, the answer is that I read the guides. They are extremely readable and it doesn't take that long. Like a couple of days. You might be surprised how much is retained by just reading through them, even without actually trying things out as you go.
I would like to stress: read the guides, not the docs. Use the docs for reference.
Programming is not regurgitating recipes without understanding. Copilot can do that. Programming is actually understanding both the problem domain and the solution space, and knowing how to find some permutation of elements in the solution space to address anything in the problem domain.
The rails guides document about 10% of the problem domain. That's mostly ok, because the problem domain exists in the wider world, and there's lots of documentation elsewhere. The problem is that the rails guides document about 1% of the solution space. And that's an issue, because rails claims to be the solution space.
Rails routing is done by passing a block into the framework that's instance_exec'd on... Something. Want to know what, so that you know what API is available to you? Too bad. Here are a list of recipes for the couple most common things you might want to do. Want to do anything more sophisticated, or just understand what your options are? Uh, sorry.
Oh, you want to set and read cookies? Here's a recipe for how to read cookies and how to set them with lots of options. You changed how you're setting cookies and now browsers are returning two cookies of the same name and you want to know how to detect and fix this? Silence from the rails guides! (In fairness, the rack documentation actually included enough information to solve that. But it wasn't mentioned in the rails guides about cookie handling. And the rack documentation was a specification, not a guide. It actually tells you what pieces there are and describes their semantics.)
And it just goes on and on. Rails has about one hundred options for every one actually mentioned in the guides. In some sense that's a good thing. The guides only give you an incredibly limited set of tools. It's very good that the rest exist. But it means that the guides are a very bad way to learn rails, because they don't give you enough information to solve unforeseen problems yourself, or even enough information to understand code someone else wrote to solve those issues.
They put you in the position of hoping someone else anticipated your weird problem and already told you how to solve it. They don't equip you for solving anything weird by yourself.
If you want to know more about an API, there's https://api.rubyonrails.org and the classes are quite will documented. These docs don't show up in the guides and might be what you're looking for. I should also point out that the API docs are directly linked in the header of the Guides.
Specifically for routing, there's lots of additional detail here: https://api.rubyonrails.org/classes/ActionDispatch/Routing/M...
Call me cynical, but the problem with this argument is that professional software development is about making something that fulfills a set of requirements, and ideally is modular+generalized enough in its design that it can be reused in the future to reduce future development time+costs.
With this in mind, I can see why the Rails documentation wouldn't really care if you learn how Rails works- all they care about is that you know how to use it.
This isn't to say that the desire for greater understanding is bad, just that it's not an effective way to keep an aging, tried-and-true web framework relevant.
Documentation is important. Otherwise you’ll just google for tutorials which are often outdated and still don’t cover the architecture/design.
It’s also fun to see all the little decisions and tools available if you read (properly written) docs
Granted you need to have proper docs
This is a ludicrous approach for most. Sure, if you learn from reading and love to read technical manuals, go for it. But to imply this is the best way for most to learn is completely ridiculous.
It really doesn't take more than a few seconds to figure out why your analogy of learning a language by reading a dictionary written in that language is both stupid and inapplicable here, so I'm not going to try to further address that aspect of your comment (especially since you don't seem inclined to directly respond to anything in my comment).
I’ve been surrounded by so many rails fans who use it for every possible problem. “If all you have is a hammer, everything is a nail” was the epitome of what was happening. Then being left with trying to sift through old versions of documentation, trying to figure out what is the “current” way of doing things in rails vs the previous ways, aye yi yi. Rails has definitely left me with a sour taste in my mouth.
I’m not saying rails is bad, it is great in so many situations. I’m just saying it is not a silver bullet, and the cult behind it has some real blinders on.
I stand by my original argument though that for most people, reading documentation top to bottom isn’t the best way to learn. If it works for you, great.
Not once did I read a textbook front to back.
there are about 35 guides in the rails guide list and half of those are digging deep into the framework... reading the first 10 of them would get you about 95% of what you really need to know in rails so that you can look up stuff later. hell even just doing the getting started guide walks you through a fairly complete rails application.
i'm working (slowly) on a personal project in rails 7 using all the hotwire with importmaps newness, and so far, it's been so much better than recent rails' diversion into all that node/yarn/webpacker mess.
it's not a ton of investment compared to how much time it would save you if you use rails later.
"Hey, thing xyz is super confusing, can you (help me use it|explain how it works|rewrite it so I understand it)?"
"Did you read the document I sent? The document (has sample code that does the thing you're trying to do|explains how it works|explains why the simpler approach doesn't actually work in practice)"
"...No."
It's incredible how some devs can learn 15-20 different programming languages, and completely forget English in the process.
One of the grave dangers that older/wiser programmers have learned is to stop trying to pathologically "drink the entire river". Programming has a constant deluge of new frameworks, tools, and publications coming out, and it's easy to fall into the trap of thinking you need to know, well, everything. I know a lot of 'aspiring programmers' who accomplish next to nothing precisely because they waste most of their time reading about programming instead of actually practicing it. It's sadly rather similar to 'aspiring writers', or any other craft — some reading is helpful, but not when it crowds out the actual task it's meant to teach. Life is short, and you have a choice between "actually making things" and "doing prep work for making things". That's all reading the docs is — it's just prep work. It's completely useless unless it parlays into actually accomplishing things.
There are semi-rare cases where some language/framework is actually teaching you new fundamentals and is worth deep-reading to gain core skills as a programmer. Haskell broke new ground. Lisp was enlightening. Smalltalk was a worthy historical study. Rust is genuinely changing things. Unfortunately, Rails just isn't special.
When I was considerably younger, I used to pathologically do this — I used to buy books on programming, and read them like a school textbook "exam cram". I read entire books on languages (like Perl) that ended up exiting the zeitgeist before I ever did any work in them — and I now have no reason to do so (I feel sorry for Perl, because Larry Wall seems like a cool guy, but perhaps it's a testament to its influence on other languages that it no longer has uniquely redeeming features). I even read books on various applications. Naively, at the time, I looked at learning as a pure, unalloyed good — rather than a dangerous spend of lifetime I'll never get back.
I deeply regret wasting that time on that instead of learning a meaningful skill.
This is why Rails is so good at what it does.
I don't want it to be special. I want it to be mature, work, and allow me to be productive. I have work to do!
You do know you can just turn off the parts you don’t want, don’t you?
Don’t want database support? Just turn it off or don’t include it in the first place.
Rails doesn’t have to be “special” it just has to get the job done and it does.
Where it gets even trickier, is that these days nobody is responsible for just a small numbers of technologies.
Does your app use the internet? Read about TCP/IP and DNS and other internet technologies top to bottom. Does your app use a database? Read the DB docs top to bottom. How about multiple data stores? Is you app publicly facing? Read about 100 different potential security issues top to bottom. I could go on...