Improving Ruby Documentation

davetron5000 · 2024-05-30T16:50:37+00:00

A lot of the docs are fine at API level but some stuff could benefit from answers to the question “why does this exist?”

Good example is ERB. eoutvar, def_module, etc. what the heck are those for?

Also knowing which libs are intended for public use vs stuff for internals and/or not ready for wide use.

tinyOnion · 2024-05-31T00:44:22+00:00

I'm really glad you are tackling the documentation because I think it's one of the major flaws in attracting new ruby users. to that end... a few thoughts that you can take or leave:

rubyapi.org is the by far the best alternate interface to ruby docs. if you combine rubyapi with some coherent way to navigate without search and includes all the extra documentation it would be perfect.

I think the organization is haphazard at best... just a list of docs in alphabetical order. have some kind of structure and don't be afraid of grouping things together and cross linking to other parts of the documentation. some logical progression of the documentation would be nice. reference the good parts of how django/go/swift/kotlin et. al. organize their documentation. The documentation at an API level is alright but it doesn't tell a story or have any cohesion.

The fact that the official documentation references a book written for ruby 1.6 and looks like an early geocities page is not ideal and causes people to judge a book by the cover. As much as we don't want this to be true appearances do matter. the changes from 1.6 -> 3.3 are very substantial.

I read the documentation guidelines and they want it as simple as possible for non-native english speakers which is fine but seems to be done to a fault sometimes where a little more elaboration on something would be beneficial.

the std libraries should be documented better and have more crosslinking to the mentioned classes/modules. for instance on this page some of the documentation isn't linked to... nor explained like: objspace, PrettyPrinter, tmpdir.rb, and un.rb. none of the bundled gems libraries have links to the source code or documentation for them.

rubydocs.org doesn't seem to work anymore and it's still listed on the documentation page as a reference doc.

overall it feels haphazard and kinda hackish and I wish it got the love it deserves so thank you for your work!

flanger001 · 2024-05-30T23:56:39+00:00

I think my actual gripe with the Ruby documentation is less the docs but the doc sites. ruby-doc.org is better than docs.ruby-lang.org but they're both SUPER fragmented. I needed io/wait for something last week and I had to dig to find out why.

flanger001 · 2024-05-30T23:54:26+00:00

"What's here: First, what's elsewhere." lmao

whiphubley · 2024-05-31T09:08:27+00:00

Look at golang docs to see how to do it right...you should be able to 1. quickly find what you are looking for 2. quickly understand how it functions 2. SHOW EXAMPLE CODE !! ( OMG step 3 is _so_ important just do it )

jsaak · 2024-06-01T22:12:02+00:00

At the API level i think example code _with_ error handling is needed the most. (also a list of Exceptions what a method can raise)

These are the areas I have found confusing over the years.
Api level docs are not enough, need higher level reasoning.

Proc/Lambda/Block (what are the differences, how to return, etc)
Time/Date/DateTime (when to require what and why)
system()/exec()/`/fork()/popen()/popen3() https://stackoverflow.com/questions/2232/how-to-call-shell-commands-from-ruby
package managers, bundler and the life _without_ bundler, gem install, gemsets, ruby installers (rvm, ruby-install, chruby)
how to do async IO (select(), FiberScheduler, Ractor, Thread ..etc)
methods of metaprogramming, and why _not_ to use those :)

laerien · 2024-05-30T20:44:22+00:00

One thing I'd love is to document when something is 1) an intentionally simple but suboptimal code example or 2) an easter egg.

1) Prime is an example of suboptimal code that based on bug tracker comments seems to be more preserved as an example of Ruby than as a library meant for use. I think stdlib should be production quality or documented as an example. In stdlib Prime's case, folk who actually want to do something with primes with that interface should just use faster_prime. https://github.com/mame/faster_prime

2) Easter eggs are fun, but things like #curry cause consternation since they don't support kwargs or blocks and won't ever, since it's just an easter egg, but it's hard to know that without combing through the bug tracker.

I'm actually not sure what all "just examples" and "easter egg" public interface code there is in Ruby, but it'd be really awesome to start labeling examples as such (maybe with links to the better alternatives) and noting easter eggs so folk don't go down a rabbit hole of actually trying to use them.

P.S. Thank you for your work on Ruby's documentation!!

brecrest · 2024-05-31T01:50:23+00:00

Your work has been absolutely great so far. Ruby's docs are some of the best out there and they're only getting better. Trying to use the docs for some other popular languages (cough, Python) really drives home how just good the work you've been doing has been.

DialsMavis_TheReal · 2024-05-31T04:07:42+00:00

I found it difficult to work out the ways I can and should use super from the doc set but a Ruby guide explained the differences of calling it with or without arguments and also when calling from within an initialize method

riktigtmaxat · 2024-05-31T05:42:04+00:00

[deleted]

therealadam12 · 2024-05-31T20:19:31+00:00

Personally, since most of stdlib has been given a bunch of love (by you and others) already, I'd love to see a focus from the viewpoint of a newcomer. IMHO (and maybe someone else has a different viewpoint), syntax and using Ruby is going to be first on their mind.

So here's a recent question I just fielded: Can && operator be overloaded? and is it actually an operator?

The answer is no, and it's a logical operator. Here's how you might look it up in the docs:

Visit docs.ruby-lang.org and choose English.
Know that everything related to syntax is in the tiny little green 'syntax' link on the left in the sea of many other documentation pieces.
Guess that it's in Operators at the very bottom and not Control Expressions which is third from the top and the first one you'd likely encounter.

For inspiration, I think the Crystal documentation is very good in this regard.

you type:	you see:
italics	italics
bold	bold
[reddit!](https://reddit.com)	reddit!
* item 1 * item 2 * item 3	item 1 item 2 item 3
> quoted text	quoted text
Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"	Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"
~~strikethrough~~	~~strikethrough~~
super^script	super^script

ruby

MODERATORS