Contributing to Ruby Documentation

First, thank you for reading this. It suggests you are interested in contributing to Ruby’s documentation.

The Ruby API docs, such as what you see on this site if you look up information about the core or standard libraries, is generated from comments in the Ruby source code. That means that in order to help update or add to the Ruby API docs you will need to get a copy of the Ruby source code. It also means you need to be familiar with RDoc syntax. You also need to know what parts of the Ruby source are most in need of improved documentation (though it is quite possible you ended up on this page because you’ve just come across some docs you found lacking.)

Getting a Ruby to work with

The Ruby source is managed using both Subversion and git. The repositories are kept in sync so, technically, it doesn’t matter which one you work with. As a practical matter, though, contributing to the docs is easier using git.

Note: If you’ve never installed or used git, then the rest of this may make no sense. This is not really the best place for git intro; please see Github’s set-up help page.

The first step is go to github and fork the Ruby git repo, at https://github.com/ruby/ruby

Grab a clone of your repo:

git clone git@github.com:<your-github-name>/ruby.git

Add the original Ruby repo as an “upstream” source. This will allow you to grab any updates to the Ruby source and pull them into your own copy.

git remote add --track master upstream git://github.com/ruby/ruby.git

To verify the remote repository was added run

git remote

You should see the new remote repo listed.

Now you can fetch any changes by calling

git fetch upstream

Do this before you start any editing to be sure you’re working off a current copy of the source code.

Picking what to document

Eric Hodel maintains a ruby documentation coverage report that can guide you in selecting what to work on. However, having docs does not always mean having complete or proper docs. While it might be better to create documentation where no yet exists, improving existing docs is also welcome.

What’s key is that you understand the code in question and feel confident in writing clear, concise documentation with practical examples.

Understanding RDoc syntax

A standard Ruby installation includes the rdoc tool, but there is also an RDoc gem. The gem is going to be more current, so please install it.

RDoc usage and syntax is described in the RDoc gem docs

Style Guidelines

Because your documentation will be added in to the Ruby source code, it’s important that it be properly formatted. Use the following guidelines when writing to ensure that your contribution will be accepted by the Ruby maintainers. It’s a long list, but don’t let it scare you. The ruby-doc mailing list is a great source of help if you’re unsure about how to write your documentation.

  • Documentation embedded in code must be wrapped to 80 characters, including comment characters and white space.
    • When the in-line comments are processed by rdoc, the hard-coded line breaks will be replaced with flowing paragraphs. But when viewing the code the 80-character limit plays nicer with code editors.
  • Use :: for describing class methods, # for describing instance methods, and use . for example code.
  • C methods must have call-seq. This describes the arguments and return values of a function.
  • All documentation should be written in full sentences that start with a capital letter and end in a period.
  • Separate documentation from the comment character by one space.
  • Example code within comments should be indented 2 spaces in from the surrounding text. This will signal rdoc to parse it as a code block and apply the correct formatting.
  • Include plenty of examples. Also, include the appropriate ‘require’ statements in any examples.
  • Don’t document the internal behavior of methods. Describe them from a perspective of purpose and function.
  • Try to include information on every page of the generated documentation or at least a link to relevant information.

Submitting your work

After making or adding any documentation to your copy of the Ruby source code, you next need to generate a “pull request” for the original Ruby repo. If you’ve never done this it is explained on GitHub: Creating a pull request.

First, make sure you have committed your changes back to your own repo. If you’ve added any new files, make sure you’ve used git add to add them as well. Try to use brief but informative commit messages. Then push your changes back to your GitHub repo.

Follow the instructions on that GitHub to create a pull request for the main Ruby repo.

Questions? Comments?

If you have any questions or comments, subscribe to the ruby-doc mailing list and post there. The Ruby community is helpful and responsive, so don’t be afraid to ask.

Thanks for helping!