Ruby's achilles heel
Most folks point to Ruby’s MRI implementation as Ruby’s greatest weakness. Luckily this is fixable and fixes are in the works. The bad news is that the true weakness about the language will be much harder to solve. Ruby’s docs are horrid, and in this post I provide a small but telling (and scary) example. As a Ruby fan, I fear the state of the documentation the most.
Comments
Cool, where can I find the documentation patch you wrote to fix it?
The whole documentation /process/ is the worst part IMHO. Providing “patches”, using mailing lists and dealing with things in a development-type way is great for, well, developing software. For documentation? No.
I’d have contributed documentation myself, rather than write articles and tutorials, but the process is poor.
Just to add to this by elaborating on my last comment, I think the documentation sucks because the tools suck. DHH has talked about how Rails made Web applications sexy to develop because Rails, as a tool, is just so fun and easy to use.
Contributing documentation to Ruby, however, is not fun or easy. The mailing list is almost dead (about 7 relevant posts so far this year) and it seems to be a thankless task.
I’d be interested in doing something about it, though I suspect some of the more.. “established” members of the Ruby community could be against significant documentation efforts that differ significantly from the current system.
There is certainly an atmosphere of obscurantism in some corners, but perhaps a bold effort from other branches of the community would have a cleansing effect.. you never know! :) Food for thought..
Chris: Thanks for an absolutely incredibly comment. You make some really good points. (Well, except that I know everything. I don’t. I just know how to look that way ;-))
You have definitely helped solidify and form some ideas for me. The thing about allowing people to take risks and innocently make mistakes in the documentation is key. That’s how Wikipedia works (the whole “Be bold!” thing) and it worked out well. That’s rarely accepted in code, but in documentation it’s a great idea.
I am not entirely convinced yet whether this sort of thing is something I want to bite off. It might be more than I can chew on, but if it took off socially and there was the right framework around it in terms of the design and the features, as you say, then it could probably be a winner.
I’ll keep thinking, but thanks for a very inspirational comment.
I’ve got to say that I find the entire “patch the documentation” idea extreme. What I used to find worked really well was the PHP docs. An OFFICIAL section (not unlike the current docs), followed by a river of user comments. The core of this system is great.
The thing that keeps me from contributing to the documentation in any way is exactly what Peter is talking about: the patching process makes me want to eat my fingers.
The patch process is so teeth-pullingly heinous that my brain would basically rather I did some real work instead of spending over the odds to commit and get “approved” a small patch to the docs. Lifo is making good with his Github documentation project, but even then there is this “glass ceiling” where you need to have written a patch or proved to someone that you can write decent docs. What the hell is that about? Is Rails the fucking masons?
Noobkit is some of the way there, but it illustrates my second problem with contributing to the Rails docs ecosystem. The current official system is so fucking bad, that in the back of my mind I think: “someone in rails-core or the caboose circle-jerk must be baking something up which is going to be the definitive docs system”. I mustn’t be alone in thinking this, because even though you can post comments to noobkit, there are virtually non on there. Oh yeah, the search also sucks balls, but not as much as the search in the official API.
The rails documentation is so ultra fragmented that it seems to be completely the opposite of the rails concept - one framework to rule them all. I hate to say it, but before things get any better, the community needs it’s leader(s?) to retake control of the documentation (and community around the docs) and focus all the blog-posting productivity that rails generates into 1 focal point.
Once upon a time I had high hopes for the Caboose documentation project, which since raising over $20k last year has barely uttered a peep. $20k. It’s not the mint, but we’re just talking about a documentation community site. With official backing getting the users behind it, think of the rails docs and community system you could create with $20k.
There seems to be a project called DocBox in this years Google Summer of Code program that deals with this problem.
@chris: All your points are very true, and should definitely be considered by the author of DocBox. Here is the GitHub location: http://github.com/iownbey/docbox
Lol, what happened here? … My last post got mixed up with the poster before me. So now it looks like I wrote all that! Maybe because I made a mistake in my html markup? I don’t know…
My post starts at: “There seems to be a project called DocBox…”
Fixed the post formatting issues, thanks! It was an unclosed A tag.
Post a comment