[sodapopcan]

I was going to say the same thing and figured someone else already had.

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.

[chowells]

I've skimmed the guides. They never contain anything useful. They're just a bunch of recipes. They don't actually document a darned thing.

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.

[sodapopcan]

This feels pretty stawman-y to me. They are meant to be highly digestible examples of everything the framework has to offer. They can be read through quite quickly, yet people still fail to and then you have people who don't know what scopes are or reinvent ways to do enums and what-have-you just because they weren't aware this stuff exists already. If you need to drill down into a specific topic, that's what the docs and blog posts are for. Having the level of detail you describe in the guides would only turn-off newcomers even more.

[multiplegeorges]

The guides are great for someone doing what most people use Rails for. Recipes with some side cases are very appropriate for that audience.

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

[ryukoposting]

> Programming is not regurgitating recipes without understanding.

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.

[pech0rin]

You do know you can read the api documentation right? Also you can read the code. The guides are not supposed to have every answer to bugs you encounter. 1% of the solution space? Please, youre so far off it’s laughable

[boredtofears]

Err, wouldn't you look at the source for most of these things? What framework do you use where that isn't true?

[jonahx]

The source is an over-engineered mess of nested abstractions. So yes, you can do this, and I have, but it's not a lot of fun.

[danielheath]

Want to know what’s available somewhere? Write “public_methods - {}.public_methods” to stdout.

[pricci]

I like doing "ls" in pry.

[jbverschoor]

I did the same for Java, FreeBSD, rails, and in the past the directx docs

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