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.

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:

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.