Contributing to Ruby's documentation
Update!
Iām now making it even easier than this: Read my new post about how Iāll do this for you. That said, if you want to do it yourself, the following will tell you how.
Original Article
Ruby 1.9.3 is coming out soon! drbrain has challenged the Ruby community to improve its documentation, but some people were asking about how to do so. So I made a video!
Some small errata: drbrain has informed me that he should edit the Changelog, not me. So donāt do that. :)
How to contribute to Rubyās documentation. from Steve Klabnik on Vimeo.
If you donāt want to watch me talk about it, hereās the same info, in text:
Getting the Ruby source is pretty easy. You can find it on GitHub, here: http://github.com/ruby/ruby . Click the āforkā button and clone down your own fork:
$ git clone git@github.com:YOURUSERNAME/ruby.git
After thatās done, type cd ruby
and add the main project as an upstream. This will let you keep up-to-date with the latest changes:
$ git remote add upstream https://github.com/ruby/ruby.git
$ git fetch upstream
Okay! Now that youāre all set up, poke around and find something that needs documented. I like to just look through the source, but you can also look here for a list of things that have no docs. Documentation is written in rdoc, and Iād check the recent commits that drbrain has been making to guide you in style. This commit, for example, is a pretty good template. You can also check out the formatting guides here. Thereās also this which explains some directives for .rb files and this which handles directives for .c files.
Now that youāve made a change to the documentation, you can regenerate the docs by using rdoc. First, grab the latest version from rubygems:
$ gem install rdoc
Always best to have the latest tools. Now do this to generate the docs:
$ rdoc --o tmpdoc lib/rss*
Iām passing it in an output directory with op, since the doc directory is not an rdoc directory. rdoc will complain and refuse to overwrite those files, which is a good thing. Iām also passing in a pattern of what to compile documentation for, compiling all of it takes a few minutes! In this case, I chose to document the rss library.
Now you have a website in rdocout. Open up its index.html, and poke around for what youāve changed. If it all looks good, youāre ready to make a patch!
$ rm -r tmpdoc
$ git add .
$ git commit -m "adding documentation for $SOMETHING"
Now, you have two options here. One is to simply push the change up to GitHub, and make a pull request.
$ git push origin
⦠aaand pull request. The core Ruby development doesnāt really happen on GitHub though, and so your patch may take a while to get included. If you really want to do it right, submit a patch to RedMine. Weāll use git to make this patch:
$ git format-patch HEAD~1
This says āmake a patch out of the last commit.ā Itāll tell you a file name, it should start with 000.
Now, sign up for the Ruby RedMine here. Once youāve clicked the confirmation email, open a new ticket, and assign it to Eric Hodel, category DOC, and give it your Ruby version, even though itās not a big deal here. Click āchoose fileā and pick your patch, then ācreate and continueā and BAM! Youāre done!
Letās all pitch in and make this the best documented Ruby release ever! In writing documentation, you might even find some things that youād like to help improve. ;)