Log in

What do Rails Documentation and Carrot Juice Have in Common? - Run-Time Errors
October 19th, 2008
08:03 pm


Previous Entry Share Next Entry
What do Rails Documentation and Carrot Juice Have in Common?
If you said, "They both expire before you finish them," you are CORRECT!

I am presently looking for work, and fighting off a flu. This, of course, means that I both need to interview and am unable to speak at the same time. So, I've been mostly sleeping. Mostly.

I have also been trying to hack on Ruby on Rails 2.1. Please note the 2.1, as it is not optional to note that, which is exactly what I'm getting around to. Read on...

Rails is a lot like quantum mechanics. It is extremely powerful, parts of it are deceptively simple, and if you look at anything, it changes. You quickly become convinced that Rails might as well have a no cloning theorem, because anything you copy from an existing example will behave completely differently when you put it in your application.

What's going on? Well, here are the main reasons why learning Rails today, right now, October 19th, 2008, sucks:

1. The current version of Rails, Rails 2.1, is hugely changed from Rails 1.x.

And not in a small way. The problem is that Rails 1.x was still very exciting, generating a huge amount of interest, and a massive amount of chatter-- all of which will now function as total misinformation when you are attempting to do on-line searches for information. Which, after you get frustrated with that, will bring you to my next point:

2. Practically all of the printed manuals available are for Rails 1.x.

I cannot overstate the damage this does. You're probably used to reading manuals that are not cutting-edge, and not minding that much. Sure, you miss a few fancy new API functions-- sometimes you miss something that's far, far better than the older options. However, the older options are generally still available, and you can use them. This is, incidentally, one thing that the Win32 APIs got right for a very long time, and one of the reasons the barriers to entry for new Windows programmers were so low. It is extremely important.

However, Rails 2.x changes so radically from Rails 1.x-- for all the right reasons, admittedly-- that any documentation for Rails 1.x is not just incomplete, not even obsolete, it is actually dangerous. If you are a new developer, you are far better off, as near as I can tell, never even opening a Rails 1.x manual. I am not kidding. Remember Direct3D Retained Mode? It's like that.

One of the few books (and, as of this writing, it is a stark landscape out there) recommended for 2.x development is "Agile Web Development with Rails". While I respect the authors, and definitely recommend Dave Thomas in particular, there is something you should understand about this book, and most of the available texts. As near as I can tell, there are no Rails reference books. I mean that very literally. "Agile", in particular, is one of the worst-indexed texts I have ever seen. It is intended to be read in a largely linear fashion, from cover to cover. That may indeed be as intended, but at the moment, the practical upshot of this is that one of the few books that covers the current technology is extremely frustrating to try and use as a reference. That said, if you have to buy something today, that's probably what you need to buy.

Incidentally, Ruby itself is a different story-- there are a number of excellent books on Ruby itself, and that situation is mature and useful.

3. The technologies most helpful for new developers are the ones that have changed the most.

If you are diving into Rails, the word you will come to both love and hate is scaffolding.

Scaffolding involves the automatic generation of code, yes, but it also automatically gives you directory structures that are consistent with Rails (which is very important) and a number of placeholders that wiil prove useful. The problem is that you will be almost immediately tempted to use it as a huge crutch. Initially, this is not bad. But, like all code generators, you will wind up in situations where you either have to start maintaining things yourself, or re-run the generator-- which, yes, will stomp on some of your changes.

So early on, you will be critically interested in two things: how to make the scaffolding generators do things, and how to modify things manually in a meaningful way. Some of this is extremely non-obvious, such as the fact that the structure of a "class" is, by modern standards, actually specified in a database migration.

The primary problem-- which I have absolute confidence is making prospective Rails programmers jump ship in droves-- is this:

Scaffolding has completely changed, and ActiveRecord/REST techniques have changed significantly, to the point that nearly all printed examples are grossly misleading (and non-executable), and the vast majority of information available online is either in the same state, or worse, suggestions and experiments left over from the transitional period, written by experienced Rails 1.x programmers, and largely intended solely for consumption by other Rails 1.x programmers trying desperately to keep their applications running.

The closest thing I have for "advice" for you on this is to learn how to use the date range restrictions on Google, and restrict your search to the last year only, at the loosest. Beware of reposts of old, outdated, and misleading information. Shun "suggestions" to modify Rails' own source code, but don't be afraid to read it-- just beware that some of the comments and code in there are just as obsolete as the documentation. Orphaned or legacy functions may not have been pruned-- don't get confused by them.

4. Platform sprawl.

"Platform sprawl" is a term I've used before to describe platforms that are reluctant to draw and observe a clear line between the base platform and its extensions. It can cause some serious problems if it is not addressed reasonably early, and is the reason Cindy Hahn and I helped split wxBase out of wxWindows (wxWidgets, these days) at Surveyor, for example. You have platform sprawl when the typical "answer" to a "how do I do X with Y?" question is, "install Z", for almost all questions of that form. When things get to that point, the ability of developers to meaningfully communicate is largely dependent on whether or not they happen to use the same set of plug-ins, a situation exacerbated by the plethora of different solutions to any given problem-- all from different points in time.

In Rails, platform sprawl is everywhere, and the result is that developers run screaming for plug-ins far more often than they solve "simple" problems that involve complex research.

This issue drives me bat-shit crazy, and if you want to see it in action, search for this phrase: "rails time zones". (Oh yes, we get to go through that again.) I'll save you some pain and suffering and inform you that this has largely been fixed, and it has been fixed in Rails-- but you will find next to nothing about that anywhere. What you will find are a ton of extra plug-ins and libraries and god knows whats that are deceptively simple to install, maddening to configure, and, worst, totally obsolete.

As an example, one thing you will probably want to do at some point is a drag-and-drop sortable list. It's cool, it's modern, it's far faster than most other UI mechanisms for doing the same thing, at least for short lists, and it can be done in Rails and JavaScript ("AJAX", if you like, though strictly speaking this is simpler than AJAX). It CAN be done this way, and you SHOULD do it this way, at least once, so that you understand how the hell it works. However, there are approximately 50,000 "gems" (installable Rails modules) that will do this for you, and any time you spend trying to figure out how in the hell to get them to work (because, after all, their example documentation won't have been adequately updated, either-- only their API docs, if that) is time that goes down the plugin-specific drain.

An extremely frustrating percentage of the answers to even simple questions about how to do things using the nuts-and-bolts of Rails itself, and custom JavaScript, with or without Prototype, etc., are met with "Oh, just use this plugin". Maddeningly, another large chunk turns out to be cobbled-together code chunks for old Rails versions that either no longer work properly for Rails 2.1, or will take you off into the weeds, reading about techniques that, even if they still function, are totally obsolete, replaced by far more elegant and practical techniques-- which you will be completely unable to find documentation for, anywhere.

5. Context-free API documentation

Obviously, you should make the most of the content on the official Rails site. The problem is that the only stuff on there that consistently has any kind of completeness to it is the API documentation, and because syntax in Ruby is so flexible, you really need to see larger examples to get the idea of how to use API elements in effective block structures for their typical use cases. This is usually lacking in the API documentation, which is not exactly a problem, since in many cases it would be large enough that it should be elsewhere anyway. The problem is that "elsewhere" is often a wiki page that doesn't exist yet, or worse, one that hasn't been updated since 1.x.

6. The "Hail-Mary" wiki

Having used many wikis, and configured more than a few, let me observe that there are typically two situations in which an organization deploys one:

A. The organization has a large body of content that would either be difficult to organize hierarchically, or which benefits greatly from extensive cross-referencing. Small experiments with a wiki show a huge and immediate increase in quality and productivity, and the wiki quickly becomes the primary mechanism for editing and retrieving information.

B. The organization realizes that it has no idea how to organize its information, or that the intended structure is proving to be largely ineffective. As a result, a huge amount of information is effectively getting dropped on the floor; worse, stale information competes with current information during search operations, and identifying the definitive version of a document is not straightforward. With no other idea how to proceed, a wiki is rapidly deployed in the same way that a football team throws a "Hail Mary" pass-- under duress, with little time on the clock and no other options. Because, like, wikis are fantastic. I mean, gosh, haven't you used Wikipedia?

Your humble analyst has deduced that the Rails wiki is the result of situation B.

So what are my conclusions? Ugh. I don't know. Maybe that I'd like to go into cryo for a few years and come out when all of this crap has sane documentation? I know-- let's do a FAQ. Because, like, FAQs are fantastic. I mean, gosh, haven't you read the Rails FAQ?

Q: Is Rails a mature technology?
A: Maybe. If you have at least a few top-notch developers who have lived and breathed Rails for the last few years, maybe.

Q: Is Rails deployable?
A: Yes, provided you do NOT automatically update Ruby, Rails, or anything related to it without paying a lot of attention.

Q: Given all of this, is prototyping in Rails really that much faster?
A: Believe it or not, yes, it is. Once you figure something out in Rails, you will get a lot of leverage out of it, and the next project will be much easier. However, the critical thing to understand is that while the learning curve is not always steep, the curve has discontinuities at the moment. So it is difficult to say how often you will get stuck, but it is easy to say that when you do get stuck, you may have a hell of a time getting unstuck.

Q: I need to do something from scratch, right now. Should I even use Rails?
A: If you are already a mad PHP ninja, and you need to do something quickly, keep throwing shuriken for the moment. If you are not, I think Rails has a better future ahead, but PHP may be a lot less hassle to learn at the moment. If you are looking for employment, you may be thinking that technologies this hard to learn tend to be short on qualified developers, and you are correct, but this is the last technology you want to try to snow somebody on. Hiring managers should likewise be damned sure that their Rails gurus shake and bake any potential hires claiming serious Rails skills.

Q: How well does Rails integrate with source-code control?
A: Not in a straightforward manner. It can and should be used, but expect this to take some research, thought, and design prior to deployment.

Q: How familiar should I be with Ruby before trying to learn Rails?
A: So-so. A novice Ruby programmer who has written a few object-oriented Ruby applications should have almost all of what they need. You should understand block structure, iterators, and namespaces, in particular, as those have significant differences from most other languages. Class and function definitions are similar enough to other modern object-oriented languages that you can pick them up. One thing you need to know cold, though, are naming conventions-- capitalization, special prefixes, etc. Rails takes those rules and adds a lot more (like pluralization rules, which I am not even going to get into here) so you really have to have them wired. Buy Dave Thomas's "Programming Ruby" (the "pickaxe" book) if you haven't already-- there is no substitute.

Q: Do you have any resources to recommend?
A: Only a few. First, for books, "Agile Web Development with Rails", but see above. For any printed reference, before you even read the back cover, open it and check the printing date. If it's more than a year old, put it back on the shelf. For websites, check out PeepCode. PeepCode's screencasts, etc., are commercial products, but that is a good thing, as it means that they are currently one of the only places that has both the ability to rapidly iterate new versions of their training materials and the financial incentive to do so. Other than that, I could list a bunch of stuff, but you're going to come across most of it on Google, and there's very little I can recommend consistently. Plus, half of it will be out of date by the time your Google search for "frustrated rails developers" lands you on this page, right?

Finally, there are the Rails mailing lists, and probably a newsgroup or something somewhere. Why am I waiting until the very end of this drawn-out monologue to even mention these?

Because, quite bluntly, if your best resource for documentation is a mailing list, a newsgroup, or somewhere else where someone can ask a question and wait hopefully for a reply worth a damn, then you do not have adequate documentation-- and I hope that is the one thing that you, as a professional, walk away with.

That, and always state the date of authorship inside your work-- files are harder to smell than carrot juice.

(6 comments | Leave a comment)

[User Picture]
Date:October 20th, 2008 05:36 am (UTC)
Both amusing and informative, and also confirming of a suspicion I have had for a while now.

And yeah, I just bet, there are at least A THOUSAND little modules out there claiming to be "AJAX" implementations of common modern UI widgetry, like drag-sortable lists and toolbars and embedded RTF/HTML editors and yadda yadda. They're gussied-up detritus from when their authors were learning how AJAX works, and their best use to you is as a scrapyard for ripping out clever pieces as you build a module of your own, to suit your own needs.

This is because in order to make anything in AJAX that doesn't look like a post-transformation Tetsuo, you need to tear apart the existing implementation and digest the component parts.
Date:October 20th, 2008 02:03 pm (UTC)
While I agree with you on some points, I think it's just a matter of knowing where to look. The changes between Rails 1.x and Rails 2.x are extreme, and do require some awareness when expecting to be able to copy and paste a working block of code from a google search. But seriously, using google to search for working code is risky in any language. I'd argue that the pages of non-working, dead-wrong, poorly-written, uber-ugly code outweigh the good code 5 to 1 in any language, not just Rails.

The lack of a good Rails reference book is a valid complaint, but the platform is changing so much I doubt anyone wants to write one. But good information is out there:

Rails Casts has excellent free screen casts covering basic to advanced Rails concepts (I LOVE this resource)
Rails Envy has some good podcasts
Ryan's Daigle usually covers really new Rails features
Stack Overflow is a good resource for any developer, really.

And where google searches fail, searching delicious.com for what I'm looking for has given decent results in the past.

Other points:

I think knowing Ruby before you know Rails can go a long way. I tried to learn both at the same time (Right when 2.0 came out, so yes, the scaffolding thing was very annoying) and it got confusing trying to figure out which part was Rails, and which part was Ruby.

Also, I'm not sure what you mean when you say it doesn't integrate well with source control. What's so much more difficult about setting up git repository with a rails project than using another language? They're both a folder full of files.
[User Picture]
Date:October 20th, 2008 08:11 pm (UTC)
"I'd argue that the pages of non-working, dead-wrong, poorly-written, uber-ugly code outweigh the good code 5 to 1 in any language, not just Rails."

As a counterexample, go trolling around for Perl code and see what the ratio of broken-to-working is.

Rails really is in a much more volatile position.

Edited at 2008-10-20 08:12 pm (UTC)
Date:October 21st, 2008 11:54 pm (UTC)
Hi Jeff-- thanks for the references, I'll check those out.

I agree that Google shouldn't be your first choice-- the problem is, most people's first choices (decent texts or official documentation more comprehensive than an API) simply aren't there, and, until you find some sites you gradually come to trust, most developers are going to run out of options and go to Google.\

Since, at that point, the information they find is going to conflict, they're going to want to run the code samples so they can try and figure out which ones are actually current, and that's when the fun starts.

As far as the source code control, ah yes, you used the one word that immediately strobe-lights the confusion: "git".

Let me clarify:

I feel a technology "integrates well with source code control" when I do not have to switch to a different source code control package to use it.

I happen to use Subversion, and while it has its warts, they are related to branching and merging, not basic operation. Using CVS or Subversion, a Rails project requires careful consideration of which files will be under revision control and which will not. This happens at initial setup and continues to surface during development.

In a mixed development environment, you will get strong resistance from a team if you expect them to become proficient on multiple source-code control systems-- not unreasonably, in my view-- and you will also get some nasty mistakes, as people forget which quirks go with which system.

Thanks for your feedback! Have any favourite gems to recommend?
Date:October 20th, 2008 05:39 pm (UTC)

Did you have a look at http://guides.rails.info ? Have a look at http://hackfest.rubyonrails.org/guide to see the idea behind guides. We're going to keep the guides inside Rails source and if any patch changes the relevant stuff, patch authors will be required to update the guides in order for the patch to be accepted to Rails.
Date:October 22nd, 2008 06:23 pm (UTC)

Staying Up To Date

I'm glad you found PeepCode useful!

Developer support for our products has been extremely positive and it has helped us to fund hours of research and documentation into other topics way ahead of the major book publishers.
Powered by LiveJournal.com