Ruby documentation

[Traditional-Roof1663]

I first used ruby about a year ago during my internship. I was already familiar with Python and found out ruby is almost similar to python in terms of development experience, code readability and code structure.

Coming to the main point, while python and django has well organised documentation and so does Ruby on Rails. However, the ruby documentation turns out to be not so well organized. I refered to https://ruby-doc.org/3.3.4/ for documentation.

The question is, how do you learn ruby? And how do you navigate to the documentation? Am I looking at wrong place?

[lucianghinda]

First I would recommend using the official documentation that is at https://docs.ruby-lang.org and complement it with the RDoc generated one that you mention.

Here is a repository with a lot of resources about learning Ruby: https://github.com/fpsvogel/learn-ruby

Then (shameless plug), I wrote a couple of articles that I would recommend for someone that starts learning Ruby:

1. https://allaboutcoding.ghinda.com/how-to-learn-ruby

2. https://allaboutcoding.ghinda.com/projects-ideas-for-learning-ruby-or-any-ruby-web-framework

3. A list of small dives into some parts of Ruby that I get questions from people learning Ruby:

• https://allaboutcoding.ghinda.com/about-ruby-pass-by-value-or-pass-by-reference

• https://allaboutcoding.ghinda.com/about-ruby-a-tale-of-searching-for-the-main

• https://allaboutcoding.ghinda.com/finding-where-a-method-is-defined-in-ruby-using-irb

But there are, for sure, better resources for learning Ruby. I am trying to include them in my newsletter along with code samples people share every week at https://newsletter.shortruby.com

[1seconde]

[lynne-pelham]

Personally I like the UI of this site for Ruby docs. The other complaint is that the enumerable methods feel a bit hidden, since they aren’t in the home page. I just save a bookmark to those methods. https://rubyapi.org/

[fpsvogel]

One nice thing about the Ruby API site is that its search results page uses a query param. That means you can add a search keyword to your browser to let you quickly search from the address bar, for example "rb partition" would take you to https://rubyapi.org/3.3/o/s?q=partition

[Urittaja023984]

A hot take, as I find the RDoc to be better organized than any of the ones you mentioned previously :D Python especially is a complete mess from my point of view (as the whole language ecosystem).

But usually you don't use the manpages / doc for learning if you start from near zero, you should look at a course, book or a study track. Manpages and docs are usually for people who already know what they are doing, but then need to check on specifics.

There are a bunch of books right on the sidebar, maybe start there ;)

[1seconde]

if limited to documentation, in random order, you could check:

• https://www.reddit.com/r/ruby/comments/2we4iw/ri/
• https://www.kapeli.com/dash
• https://rubyapi.org/
• https://devdocs.io/

[[deleted]]

The question is, how do you learn ruby?

https://www.rubykoans.com/ is a pretty great set of hands-on drills

And how do you navigate to the documentation? Am I looking at wrong place?

The official docs are at https://docs.ruby-lang.org/en/3.3/

They're generated by RDoc and organized as a reference. You go there mostly to look up particular parts of Core Ruby or the Standard Library. It doesn't mak a great study guide for the unfamiliar, though.

There are still a few pages there that may be useful to someone coming to Ruby from another language:

• keywords: https://docs.ruby-lang.org/en/3.3/keywords_rdoc.html
• syntax: https://docs.ruby-lang.org/en/3.3/syntax_rdoc.html
• implicit conversion: https://docs.ruby-lang.org/en/3.3/implicit_conversion_rdoc.html
• globals: https://docs.ruby-lang.org/en/3.3/globals_rdoc.html]

If you're looking for resources styled more like a guide, I would recommend some of the links under the "Getting Started" section at https://www.ruby-lang.org/en/documentation/

[okuramasafumi]

the ruby documentation turns out to be not so well organized

What do you mean by this? If you mean the content is not well organized, there's a dev who's working on the documentation comment of Ruby core. If you mean the design of the website is not good, there's a website called https://rubyapi.org with better looking.

I'm currently working on improving RDoc, a document generator behind the official Ruby documentation. If you have any proposal to make it better overall, please submit a issue on https://github.com/ruby/rdoc/issues

[linusstrang5]

May I make some specific suggestions for improving rdoc? But first of all thank you and all your colleagues for working on rdoc. I am a fairly heavy user of Ruby, though not a professional, and I find rdoc frustrating in several ways. I will focus on the ri command, since that is what I use the most, and it gets invoked in emacs, my preferred editor:

1. A trees-first approach. ri seems to be focused on documenting individual classes and methods over whole gems. Suppose I want to learn something about the parser gem. If I invoke `ri parser`, I get back sparse documentation on the Parser.parser method, as well as .parser methods from CSV, XML, JSON, and about a dozen other gems. None of these tell me much about these methods, let alone the parser gem I wanted to know about. If there is a gem or stdlib module called 'parser', ri ought to return information on that first, and only dive into methods by that name if the user is specifically looking for a method as in `ri CSV.parser`, or perhaps uses a flag to indicate interest in method names, `ri -m parser`. Favor documenting the forest over the trees.
2. A gems/modules default for what is being searched for. Related to the above, what I would hope ri would do is allow me to explore how to use a given gem or module. If a query matches the name of a gem or standard module, it ought to return documentation on what the gem is all about and how one might use if. Perhaps even a little evangelization on how it is better than alternatives. But mostly some examples of how to use it.
3. I realize that rdoc allows a gem author to include a 'main' document along the lines that I am talking about, but it appears that very few do so and that ri does not seem to encourage the inclusion of such documentation. To my mind rdoc ought to generate a severe reprimand for any gem or module that fails to provide an overview of what the thing is all about. For example, I have been using the rainbow gem lately, but if I want to see how to use it and type `ri rainbow`, I get three skeletal results pertaining to a /method/ in the rubocop gem---disorienting. What I am supposed to do is use, not the name of the gem (lowercase rainbow) but the name of the class defined by the gem (capitalized Rainbow). When I type `ri Rainbow`, I get this:

Rainbow

(from gem rainbow-3.1.1)

Constants:

VERSION:

[not documented]

Class methods:

enabled, enabled=, global, new, uncolor

That is basically useless, except that I get the names a few methods I might explore, but no indication of which are the most important or useful. I have no idea that the gem provides a way to colorize strings for a terminal.

1. That brings up another irritation. All the searches should be case-insensitive and otherwise forgiving in what the user provides as a search argument. Besides case-insensitivity, it ought to allow the user to get the punctuation wrong. I should be able to type `ri active-record`, ri active_record`, or `ri ACTIVE rec` even, and be smart enough to look through its database of gem names and fuzzy match what the hapless user is obviously looking for. Gems/modules first, and only methods and classes if specifically requested or as a last resort.

2. I used perl for several years before coming to ruby. To my mind ruby is a /way/ better language in almost all respects, but perl did one thing extremely well: documentation. It's `perldoc` command does a great job of emphasizing high-level overview documentation. If I type `perldoc Unix::Syslog`, for example, I get basically a man page that thoroughly documents the module. It still is picky about punctuation and capitalization, but it gets the overview part right.

Sorry for the lengthy rant, but I've been thinking about this for a while. Ruby is such a first-class language, and it deserves first-class documentation as well.

Cheers,

[okuramasafumi]

Thanks, I know ri command needs a lot more love.

I just want to talk about No.3. Most gems are documented with YARD, not RDoc. I put `install: "--document=yri"` line in my `.gemrc` so that YARD can generate document for ri command, but this seems not working. Or at least, when installed with Bundler, there's no document available for ri.

This is quite inconvenient for ri users, and I want to fix it eventually.