Ruby 3.4 Documentation: A Step Towards Better Ruby Documentation

Introduction

Ruby 3.4 isn’t just about shiny language features; it also comes with meaningful documentation updates. Some of these changes are reflected in the content of docs.ruby-lang.org, while others are behind the scenes in RDoc, the official documentation generator for Ruby.

Documentation shapes our day-to-day experience with Ruby, as well as the first impression for newcomers. A well-structured, easy-to-read reference can:

Decrease confusion for newcomers.
Make day-to-day Ruby development easier.
Encourage more community contributions.

From my previous post “A RDoc Maintainer’s View on Ruby’s Documentation”, I shared that there are many aspects around Ruby’s documentation that can be improved. So I want to use this post to summarize the improvements in Ruby 3.4 as the first step towards better Ruby documentation in the future.

I also welcome you to read the Ruby 3.4’s Documentation and Ruby 3.3’s Documentation to see the improvements.

Major Improvements in Ruby 3.4 Docs

1. Expanded Content & Indexing

As with any Ruby release, Ruby 3.4’s documentation received many fixes and improvements from Ruby committers and the community. But I’d like to highlight some changes that are unique to this release.

A dedicated index page helps readers jump to frequently referenced classes faster (e.g., Array, String).
The revamped Standard Library page makes navigating to related documentation and GitHub repositories easier.
More than 50 dead links have been fixed with a new RDoc feature.

The default theme for Ruby 3.4’s documentation is more mobile-friendly, thanks to community-driven CSS upgrades in RDoc. Below is a comparison between Ruby 3.3 documentation and Ruby 3.4’s doc on iPhone.
The color contrast, font size, and text readability have been improved.
Class pages now feature an ancestors list (example).
Source code is displayed more neatly.
Direct method-linking means sharing docs with specific anchors is much simpler.

3. `ri` Improvements

The rdoc-ref expansion feature now lets “ri” automatically expand and link out to relevant information, instead of just displaying the rdoc-ref reference.

ri improvements

Ongoing & Future Work

As I mentioned earlier, this year’s documentation improvements are just the beginning. Even with all these changes, these are some of the ideas I’d like to explore in Ruby 3.5:

Reorganizing top-level pages (see PR #12226) so that non-API documents (e.g., syntax introduction, implicit conversions, etc.) become easier to find.
Marking default gems on docs.ruby-lang.org/en so developers can clearly see what’s part of core Ruby vs. what’s part of default gems.

For example, ERB’s documentation page should have a badge/indicator saying it’s from the erb gem and potentially link to the gem’s repository.
Applying the latest RDoc features to all Ruby versions’ documentation.
Providing an easier way to switch between different Ruby versions’ documentation.

And other ideas that I listed in “A RDoc Maintainer’s View on Ruby’s Documentation”.

Note: Because Ruby 3.4 has been released, future documentation improvements will mostly be reflected on https://docs.ruby-lang.org/en/master/ from now on.

Community Shout-Out

We owe these updates to many RDoc contributors. A huge thanks to everyone who contributed to RDoc since Ruby 3.3 was released:

@adam12, @alexisbernard, @antoinem, @BurdetteLamar, @deivid-rodriguez, @earlopain, @eregon, @flavorjones, @hsbt, @ishe-ua, @MatheusRich, @mterada1228, @nevans, @nobu, @okuramasafumi, @omegahm, @p8, @paracycle, @sambostock, @skipkayhil, @soutaro, @st0012, @sunblaze, @tompng, @toshimaru, @vinistock, @ydah

Conclusion

As a community, we should continue to improve the documentation to make Ruby more welcoming, informative, and easy to navigate, so Rubyists can stay happy even when looking for documentation ;-)

If you’d like to contribute to the documentation, here are some resources:

Ruby’s Documentation Contribution Guide
- You can also contribute to this guide itself!
RDoc’s GitHub Discussions
RDoc’s GitHub Issues

Let’s keep the momentum going and make Ruby’s documentation the best it can be!