Contributing to Ruby Documentation

Getting Started

Contributing to Ruby documentation involves working directly on the Ruby source code. Your additions (if they are accepted) will become part of the Ruby source and distributions and you'll have your name in the credits for everyone to see. Cool, isn't it? But to work with the Ruby source, you'll need to use Subversion. If you're unfamiliar with Subversion, check out the Subversion Homepage or its book for more information.

http://subversion.tigris.org/
http://svnbook.red-bean.com/

Once you're comfortable with Subversion (also known as svn or SVN), use your favorite svn tool to get a copy of the Ruby source code. The repository's address is http://svn.ruby-lang.org/repos/ruby/trunk - and that will give you the HEAD version of Ruby.

If you are working from the command line, use the following commands (from http://www.ruby-lang.org/en/community/ruby-core): Check out the trunk as 'ruby' like this:

$ svn co http://svn.ruby-lang.org/repos/ruby/trunk ruby

This will get you the HEAD of Ruby, which at the time of writing is called 1.9. You should also grab a copy of the Ruby 1.8 branch. When writing documentation always check that your contributions can be easily added to Ruby 1.8. If not, you will need to submit separate patches for both the Ruby HEAD and the 1.8 version. Again, from the command line, use:

$ svn co http://svn.ruby-lang.org/repos/ruby/ruby_1_8 ruby

To check your additions to the Ruby source, you will compile the documentation yourself, using stdlib-doc. stdlib-doc is a specialized tool for building the Ruby source documentation. As such, the installation process is a little bit difficult. For now, read stdlib-doc's Getting Started document. Go slow and make sure you have all the necessary dependencies.

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 inline 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. For example:

/*
* call-seq:
* array.delete(obj) -> obj or nil
* array.delete(obj) { block } -> obj or nil
* ...

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.

Submission Guidelines

Once your documentation is complete, you'll submit your changes to the ruby-doc mailing list as a patch. If you are relatively new to handling patches the article Comparing and Merging Files explains this, and be sure to read the next section in that document called Making Patches. You'll use 'svn diff' instead of 'diff', but the syntax is the same.

$ svn diff > rdoc_changes_to_some_module.patch

Check to see if your changes can be easily added to Ruby 1.8. If they can't you'll need to make the changes to both Ruby HEAD and Ruby 1.8 and submit separate patches. If the changes can be easily added to Ruby 1.8, one of the Ruby maintainers can port it to 1.8 for you.

Once you've got nice clean patches and your documentation meets the guidelines, post it to the mailing list. The list is fairly active and you should see a response within a day or so. If you followed all the guidelines and your patch was accepted, congratulations! Enjoy that nice warm feeling that comes from helping out an open source project. If there were some problems, enjoy the collaboration with other contributors as you work to make your patch perfect. That's fun too.

Questions? Comments?

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

Thanks for helping!