Is the worst fucking thing on the planet. I’ve actually googled for stuff, clicked on it, and gone to redirecting cybersquatter pages, it’s so goddamned bad. Maybe I’m spoiled. The bulk of the professional development I’ve done has been with PHP, though I was pretty heavy into Perl, Tcl and other such languages at their time. Compared to any of them, Rails documentation is, hands down, the absolute worst.
Half the time I feel like they’re being too goddamned clever for their own good. But the ‘sensible defaults’ that they espouse aren’t documented anywhere, so how the hell am I supposed to know what they are? What seems sensible to me might not be sensible to you. I’ve found myself drilling down into source code more times than I’d like to count to try and figure out what’s going on. That is total and complete fail. It’s lucky that it’s so powerful and cool regardless, or I would’ve left it in the dust a million years ago.
Maybe I have to be more…loquacious in PHP. That’s fine. At least I know what to do and how to do it. 70-80% of the time I’m working in Rails, I have no friggin clue how to tell it how I want to do something. Then when I find out, it’s always something like – type two magic words into the right file, then Rails reads your mind. Awesome. I just hate that sickening feeling during that not-20-to-30 percent of the time. I feel helpless.
Then when you do find documentation, it’s all stories. “So here’s what active record aims to do, here’s different ways you can make it do things, blah blah blah.” I like my programming docs terse. I look it up, it tells me what that does. But the documentation, especially, just seems all jumbled together and awful. Or the other thing I’ll find is the opposite granularity – “Class Foo::Helper::Doodad::fwipple::dingus has methods ‘get’,’put’,’set’,’be’,’execute’. The source code to method ‘execute’ is: …….” That doesn’t help either. That’s why it’s called DOCUMENTATION. Not fucking SOURCE CODE. I feel like it’s some kind of ‘hipster’ framework – if they actually explained it to you, and regular unhip people “got it”, then the hip people would all switch to using Scala.
And, embarassingly enough, I only just ‘got’ the yield command in Ruby. That’s just sad, man. Though I don’t see the difference between a yield and an anonymous function, but I guess I’m just not that bright.
I assume it’s one of those things where as soon as you buy into it 100%, completely, and spend time just soaking in it, then you’ll fully understand. But I don’t like having to commit to that level of buy-in. I’ll continue to fiddle with it, and even choose it as a framework in whichever contexts it seems right for, but I’ll always look slightly askance at it – perhaps until I’ve been so steeped in it that I can’t look at it objectively anymore. But until then, fix your fucking docs Rails, it’s horrible.