3 ms·
IMO the biggest problem with Ruby is still the docs. When you look at https://www.ruby-lang.org/en/documentation https://www.ruby-lang.org/en/documentation, you
by int_19h 2y ago
IMO the biggest problem with Ruby is still the docs. When you look at https://www.ruby-lang.org/en/documentation 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 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 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.
- mooktakim 2y agothose old books are still good though. There's only new syntax for latest ruby versions.
- int_19h 2y agoIf 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.
- mooktakim 2y agoIts 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.
- nextos 2y agoRuby 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.
- uticus 2y agoRuby 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.
- Alifatisk 2y agoThere 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-docs.org/ https://web.archive.org/web/20230608024407/https://www.ruby-...
- tankmohit11 2y agoI 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.
- AmandaBP 2y agoHi! 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.
- strzibny 2y agoMaybe 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.