KOTPNov 14, 2024
Stan Lo

I wrote something about Ruby’s documentation. If you’re at #RubyConf this week and want to improve it together, come talk to me 🙂

https://st0012.dev/a-rdoc-maintainer-s-view-on-ruby-s-documentation

A RDoc Maintainer's View on Ruby's Documentation

As someone who genuinely cares about Ruby's developer experience, I've been thinking about Ruby's documentation for a while, especially after I became a maintainer of RDoc. And I'd like to share my thoughts on the current state of Ruby's documentatio...

Mostly Ruby DX
Nov 13, 2024 at 11:39pmWeb
Show threadKerrick Long (code)Nov 17, 2024

@st0012 My wife has been learning Ruby lately (she’s got years of front-end & JavaScript experience) and a huge pain point has been the lack of explainer text in the official Ruby docs. We’re constantly referencing Programming Ruby (the pickaxe book) and The Well-Grounded Rubyist when the official docs fail us.

Compare, for example, MDN’s page on Array.prototype.reduce vs Ruby 3.3’s Docs page on Enumerable#inject. (1/4)

Show threadKerrick Long (code)Nov 17, 2024
@st0012 The former opens with two prose paragraphs explaining the function plainly; the latter uses shorthand language better for reminding than for teaching (e.g. “using the method” rather than “sending the message to each element and using its return value instead of the block”) and uses academic language like “operand.” (2/4)
Show threadKerrick Long (code)Nov 17, 2024
@st0012 The same method documented on Ruby Master’s Docs is far-and-away better than 3.3. Sadly I only discovered this when writing this toot, because the new prose wasn’t backported to the older version’s page even though the method hasn’t changed. (3/4)
Show threadKerrick Long (code)Nov 17, 2024

@st0012 I’d love for more methods’ and classes’ documentation to be rewritten to teach like Enumerable#inject’s was, and I’d love for those updated words to end up on (compatible) older versions’ pages since new Rubyists won’t predict they will get a worse experience if they read docs for the version pre-installed on their system.

Is there a way I can contribute to either of those goals?

(4/4)

Show threadStan LoNov 23, 2024
@kerrick thanks for the detailed feedback and indeed that’s an issue.
Here’s how I think we can improve it:
1. Focus on improving the current master documentation, which will become 3.4’s doc in a month.
2. After 3.4 is out, we develop a process to backport documentation with branch maintainers. (Ruby 3.2 and 3.3 are maintained by different Ruby committers, for example)
Show threadKerrick Long (code)Dec 4, 2024
@st0012 I found a method or two for which I can improve the documentation. What’s the process for contributing? 😁