I'm Making It Dead Simple To Contribute To Ruby's Documentation
Okay! So, if you'd read my previous article on this, you'd know how easy it is to contribute to Ruby's Documentaiton.
But Steve, I'm still kinda scared.
Okay, so here we go: I'm making it even easier on you.
Send me what you want changed, and how, and I'll make a patch and submit it on your behalf.
Patches don't have to be patches
Seriously, I don't even mean diff outputs. I just got this email:
I'm eager to contribute docs but I don't know where to start: I don't mean pulling down the repo and all that, I mean, I see this link here:http://segment7.net/projects/ruby/documentation\_coverage.txt but all I see is a ton of "# is documented" comments. Where does a relative n00b begin? Poking around in the source code is, well, intimidating. I'm completely new to this but I take direction well. Just point me in the right direction. Just give me something to document, please!
I sent this back:
No code diving needed! That's part of it. Let's do this: Find the documentation for one of your favorite methods. Here, I'll pick one: http://ruby-doc.org/core/classes/Array.html#M000278 okay, that looks okay, but look at compact!:
Removes nil elements from the array. Returns nil if no changes were made, otherwise returns ary.
Why's that there? Total screw-up. For example. So, send me this email:
Check out the docs for Array#compact!, here: http://ruby-doc.org/core/classes/Array.html#M000279 . There's an extra that's screwing things up.
Done! I'll go from there. How about this one:
I checked out the docs for Time._load, here: http://www.ruby-doc.org/core/classes/Time.html#M000394
These docs kind of suck. What if I don't know what Marshal is? There should at least be a link to Marshall, here: http://ruby-doc.org/core/classes/Marshal.html And it should probably say something like "You can get a dumped Time object by using _dump: http://www.ruby-doc.org/core/classes/Time.html#M000393
I'm sure you can find something that's formatted wrong, or worded incorrectly, or anything else.
Now, the closer it is to an actual patch, the faster I'll be able to do it. A vague "this documentation is confusing, but I'm not sure why" is helpful, but will take longer. I'd rather get that email than not. If you're not sure, hit send.
Just Do It
And so I'll do it again. Scared to deal with doc patches? I'll make them up. I'm serious. I'll do it. Send them to me.
Send me patches. firstname.lastname@example.org. Do it.