Ruby 1.9.3 Documentation Challenge

drbrain | Tue, 10 May 2011 00:33:00 GMT

Posted in

Yugui announced a draft Ruby 1.9.3 release plan today with a feature freeze of end of May and a release target of end of July or early August.

I've seen many complaints in the form of "X lacks documentation" and have responded by writing it. First was an improvement of Net::HTTP along with Mathew Murphy and Yui NARUSE, next up was OpenSSL which received its first-ever toplevel documentation and today I committed toplevel documentation to WEBrick.

Both OpenSSL and WEBrick have some further documentation to flesh out the basic examples to help get you going but they need more work.

With revision 31499 of trunk RDoc reports that just under half of ruby has not even a single character of comments with over half of the classes and modules missing documentation: 

Files:        511

Classes:     1036 ( 624 undocumented)
Modules:      228 ( 136 undocumented)
Constants:   1335 (1134 undocumented)
Attributes:   738 ( 381 undocumented)
Methods:     8098 (2960 undocumented)

Total:      11435 (5235 undocumented)
 54.22% documented

What can we do in the last month or so before the feature freeze to make this release the most-documented ever? To hit 60% documentation we only need to document another 1626 items.

To do my part, if you assign documentation patches to me on the Ruby 1.9 tracker on redmine I will commit them. I'll also keep writing documentation to fill in the gaps.

If you need help figuring out what to document you can look at the ruby documentation coverage report which updates hourly. You can run the full report yourself using make rdoc-coverage or run a partial report by installing the latest rdoc and running, for example, rdoc --encoding=UTF-8 -C lib/webrick* for coverage of all of WEBrick.

To keep us from stepping on each other's toes you can check this Pivotal Tracker set up by Cory Monty.

If you don't know how to contribute documentation to ruby Steve Klabnik has an excellent tutorial on contributing documentation to ruby. Note that if you send a pull request to github I can't quickly commit your change as I don't have the proper access. comments

Comments RSS FEED

You should add instructions on how to contribute doc patches. I think forking and sending a pull request on github is enough, but I’m not sure where those pull requests land. :-/

Aaron Patterson said about 2 hours later

Great initiative Eric, looking forward to 1.9.3 and to break the 60% goal :).

Santiago Pastorino said about 3 hours later

I’d like to contribute, but would need more information about how to submit doc patches. Can you add brief instructions on what where to get the source and how to submit patches?

Daniel Harrington said about 16 hours later

I’ve added a link to a tutorial by Steve Klabnik on how to contribute, see the last paragraph.

drbrain said about 18 hours later

The “ruby documentation coverage report” link doesn’t work. Could you fix that?

bt said about 21 hours later

I’ve updated my cron job to create the report into a temporary directory then move it into place when done, after this report is run is done it shouldn’t disappear again.

Eric Hodel said about 23 hours later

+1 to @tenderlove’s suggestion. I’d like to help too…

draven said 1 day later

Just a suggestion: It would be unfortunate if two people wrote docs for the same piece of code. Could it be organized in a way that volunteers announced what part (class, method, module, …) they’d like to document? I’d volunteer for OpenSSL.

Martin Bosslet said 1 day later

+1 @Martin’s suggestion. No need to repeat work.

Cory Monty said 1 day later

Follow up to Martin’s suggestion: https://www.pivotaltracker.com/projects/289677/stories simple Pivotal Tracker project to track who’s doing which system. If anyone has any ideas for an alternative, I’m up for those, too.

Cory Monty said 1 day later

Also note that you can add tutorials to the ruby wikibook, as well.

http://en.wikibooks.org/wiki/Ruby_Programming

Cheers!
-r

roger said 3 days later

Comments are disabled