JRuby: What I Need to Know
By Eric Armstrong on Sep 05, 2007
I was recently asked, "As a developer, what kind of information do you need to be productive with JRuby?" Here are the thoughts that come to mind in
response to that question.
As always, when it comes to information delivery, the vital first step is to determine your audience. When it comes to JRuby, there are several categories, each with differing needs:
- Non-programmers who are learning JRuby as their first language.
This group needs all the basics of computing, from algorithms to compilers, from the ground up. (That audience is generally served by schools, but if someone has a logical mind, it's fun to watch them learn how to program.)
- Java programmers who are coming at JRuby for the first time
This group needs to know first, how a Java program would be translated into Ruby, so they learn the syntax differences. Then they need to know the idioms that make Ruby special. And they need to know how to access the Java classes they're so used to.
- Ruby programmers who want take advantages of the JVM.
Ease of install, threading, and scalability probably top their interest list. But after answering the question "why do I want this", they'll be most interested in finding out which Java classes they really want to use, and how to use them to maximum advantage.
- Programmers of other languages.
This is obviously a diverse group. A lot depends on which language(s) they're coming from. They won't need the basics that a non-programmer needs, but they'll need to find out how JRuby works, compared to whatever language they're coming from. So in reality, this is a catch-all category for a variety of groups. The most reasonable approach is for them to pick and choose from the material that is targeted at the other groups.
- Web developers who want to build and deploy web applications using JRuby on Rails
This group needs to know how to set up a web server and deploy an application. Then they need to know how to build one. But since Rails is, in effect, a domain-specific language for web applications, Ruby-saavy developers don't necessarily know anything about it. (I happen to fall into that group, and would love a quick entry-path into the Rails world.) Similarly, Rails programmers often don't know much about Ruby. They need an entry way that shows them how to take advantage of Ruby's power.
Each audience has several types of (overlapping) information needs:
- Razors: This is a frequently-overlooked category of information, but it's an important one. Whenever there are multiple ways to do something, you need a razor-- a way to decide which one to use (like Occam's Razor).
Nowhere is that need more evident than in the open source world, where a plethora of projects and libraries compete for user attention. When looking at Ruby gems, for example, there are generally half a dozen libraries to choose from in any given category.
Since such projects come and go rapidly, what's needed is a Wiki with an Amazon-style rating system--a system where people can create categories, add new entries, and rate them in various ways (for example, with respect to documentation, architecture, error messages, ease of use, flexibility, and exception handling. The first site that does that will draw a ton of traffic.
- Basics: How to install the language. How to set up a development environment (directory structure, tools, and tests). How to define environment variables, set up JVM options, and run a script--both from the command line and from an IDE like NetBeans--and how to access Java classes and use Java interfaces from JRuby.
But note that language precedence tables should not be included in that doc set. I was delighted to read that Tim Bray makes it a point of principle never to learn them. I couldn't agree more. After learning some 20 different programming languages, I can tell you that it would be impossible to keep them straight--and a program is a lot more readable when you put in the parentheses to make sure it does what you intend it to do.
- APIs: Java APIs are the most thoroughly documented class libraries on the planet. They set a standard for usability, and I missed them immensely the moment I began programming in Ruby. So there is a serious need for Ruby API docs that match the quality and quantity of Java's.
- Best-Practices Language Reference: Ruby lets you do things in many different ways. That's a weakness, in my mind. It makes it much harder to read a Ruby program, unless the programmer happened to be using the idioms you're familiar with.
- Mini-Tutorials: I'm a big fan of tutorials--in small bites. I don't mind spending 20 or 30 minutes learning how to do something I'm working on. But I never have the time to sit down for a week or two and work through a huge tome. I admit: I would be a lot better off if I did. Chalk it up to a character flaw. I just don't. So I need tutorials I can use in bits and bites--especially one that matches my level of expertise and tells me exactly what I need to know, in the order I need to learn it.
Fortunately, DITA makes it possible to deliver exactly that kind of customized tutorial, as explained in Build-to-Order Documents with DITA.)