Contributing to Ruby docs

Last week, I came across a few small improvements that I could make to the Ruby docs. In the past, I’ve found the idea of contributing to the Ruby repo quite daunting, but I found that it’s actually pretty straightforward.

I made some notes about the steps to get things set up locally, and I’m sharing these here in the hope that I can convince someone else how easy it is to contribute!

Getting set up to make changes to docs

First, I forked the ruby repo, and cloned my fork:

git clone [email protected]:nithinbekal/ruby.git

Before I could run the configure scripts, I had to install autoconf:

brew install autoconf

Next, you generate the configure script:

./autogen.sh

And then run the configure script:

./configure

We need a build directory where we can generate the documentation site:

mkdir build && cd build

And finally, we can generate the HTML docs. The first run of this command will take some time, but subsequent runs should be faster.

make html

This will display a link to the generated documentation. We can now make changes to the inline RDoc docs for methods and classes, and run the make html command to update the generated docs and verify that everything renders correctly.

Tips

• To make changes to the style of the docs, you’ll need to update the theme in ruby/rdoc which gets synced with the main repo.
• To update the Ruby language website, you’ll need to fork ruby/www.ruby-lang.org.
• Now that Ruby has extracted some gems out of the stdlib, some of the docs need to be updated in the gems’ own repo, even though ruby/ruby also contains that code.
  • This happened when I tried updating the docs for Benchmark.realtime in the ruby/ruby repo. Turns out I needed to update the docs in the ruby/benchmark repo, which periodically gets synced into the main repo.

Wrapping up

I recently came across the article, Why is language documentation still so terrible?, which is what prompted me to look for ways to improve Ruby docs. I was blown away by how quickly the core team reviewed and merges my PRs. I hope this little how-to helps you contribute to the docs too!