Comment by int_19h
1 year ago
IMO the biggest problem with Ruby is still the docs. When you look at https://www.ruby-lang.org/en/documentation, you see a bunch of books - some of which are considerably out of date by now - and the official "API docs". For some mysterious reason, all the actual language features are also listed under API: https://docs.ruby-lang.org/en/3.3/syntax_rdoc.html. Worse yet, there's no proper table of contents - you get a kind of index on the left, but it's alphabetically sorted, and things on the same level are often unrelated. Compare to Python, where you have https://docs.python.org/3/reference/index.html that one can just read in order and end up with a very good understanding of the language.
Ruby dev for several years, I agree with this. It’s a frustrating point, especially after you learn the language and want to use the API docs as a reference. And I say that as a fan of the language.
those old books are still good though. There's only new syntax for latest ruby versions.
If you compare, say, C++03 and C++14, it's also technically true that "there's only new syntax", but in practice this often means that hacks that used to be idiomatic before are frowned upon now.
Its not anything like that. new ruby version has "better" short hands, like {:test => 123} to {test: 123}.
Anyway, there have been updated versions of the books and content online if people are interested.
Ruby has evolved slowly language-wise compared to C++, or even Python.
Most changes have been in libraries and interpreter / VM implementation.
Updating your knowledge from Ruby 1.8 (mid 2000s) to 3.x (current) takes little effort.
But yes, sparse API documents were always a problem because a big chunk of the community was Japanese.
There used to be a site called ruby-docs.org that was very well designed. I like it a lot.
https://web.archive.org/web/20230608024407/https://www.ruby-...
Maybe people feel there is not yet time to rewrite them?
Btw I am contributing myself this year to the book ecosystem by writing Kamal Manual and Test Driving Rails.
I am sure more pure Ruby books will happen too by someone.
I started learnig rails a couple of months ago. I took a ruby crash course and opened rails guides.
The thing discouraged me to go further was that many sections has work in progress label. I thought I might be looking at the beta docs, but no. I checked the same page down to multiple major version and the work in progress was label was still there.
Coming from Django/Laravel world, incomplete docs discouraged me to try rails.
Hi! The documentation team commissioned by the Rails Foundation is working on tackling and editing the guides one by one, and removing these WIP tags once a guide is complete.
We should see a huge reduction by the time the project wraps, but because Rails itself is constantly evolving, so to is the documentation, so you will continue to see them from time to time. Consider it a sign of growth, not stagnation.