# Getting Started With Ruby

by [Gavin Sinclair]

## Introduction

This document presents some resources available to help newcomers to Ruby solve their problems, advance their knowledge, and participate in the Ruby community.

It is located in two places: the Wiki (where it was developed), and the Ruby Documentation Bundle (for where it was intended). Since the reader may see it in one without knowing about the other, both are briefly explained here.

- The Wiki is a Ruby community resource. On the Wiki, this document lives [here].

- The Ruby Documentation Bundle (hereafter known as the bundle) is a package of various useful Ruby documents, intended for ease of access, that includes this document as an introduction. It can be found at http://www.ruby-doc.org.

### Structure

There are two parts to this document.

Some Ruby Essentials
  Describes the various resources beginners should be familiar with in order to have a good foundation in the language.

Participating in the Ruby Community
  Describes the Internet resources available to all Rubyists, and guidelines for making the most of them.

They are somewhat inter-dependent, and some information is repeated between them. There are also forward references. This is because the resources and the community grow out of each other, so it is difficult, and not desirable, to define them linearly.

### Typographical Conventions

Colloquial Ruby resources are italicised (ruby-talk, The Pickaxe, the bundle) wherever they are used, and all resources - colloquial or otherwise - are set in bold where they are defined.

### Feedback

This document has become larger than I intended. It consists of personal recommendations, not official Ruby information (or anything like that). If it is useful, good. If it could be improved, I'd especially like to know. Email feedback in any case is most welcome.

## Some Ruby Essentials

When you get started with Ruby, it's important to have a good grounding. I assume you've successfully installed Ruby, but there are some packages you should install and resources you should be familiar with. The following sections provide some advice along these lines.

### Essential Learning Resources

The place where just about every Ruby beginner starts is The Pickaxe, aka Programming Ruby: The Pragmatic Programmer's Guide. This is available free online (at http://www.rubycentral.com/book) and is also included in the bundle.

When you're reasonably familiar with Ruby, but want to learn more and see how to accomplish all sorts of tasks with it, then The Ruby Way, by Hal Fulton, is the logical next step.

The FAQ (see the Ruby homepage for a link) is frequently updated with solutions to problems posted in the mailing list, and should be consulted and digested.

New to the Ruby scene are two tutorials, both aimed at beginner programmers. The other resources mentioned above assume some programming knowledge, so if that assumption doesn't apply to you, check out the tutorials first.

Every beginner (and just about everyone else) should install the bundle (the Ruby Documentation Bundle). It contains nothing original except this document, but it provides easy access to The Pickaxe, the FAQ, a tutorial and other documents.

### Special-Purpose Books

Some other books come highly recommended. See [here] for a complete list of Ruby books, and for more details of the ones mentioned briefly below.

Teach Yourself Ruby in 21 Days is reportedly an excellent guide for those without much prior experience.

Ruby in a Nutshell is a handy reference; nothing more, nothing less.

Ruby Developer's Guide contains very useful information about non-core issues like database and web programming.

### Essential Tools: ri and irb

Your Ruby installation may already include ri, but you should check the RAA to see if a more recent version is available. It is an online reference to the built-in Ruby classes (e.g. Array, File, Integer). By specifying a class and/or a method, ri will give you information about it. The information comes directly from The Pickaxe. See [this page] for more info.

irb stands for Interactive Ruby. It is an environment in which you can play around with Ruby's features and experiment. It is particularly useful for finding out various things and testing techniques before putting them in your program. For example, if you don't remember how `to_i` works on a String that doesn't contain (only) a number, why bother to look it up when you can just use irb to find out:

      irb(main):001:0> "abc".to_i
      0
      irb(main):002:0> "abc123".to_i
      0
      irb(main):007:0> "123abc".to_i
      123

irb comes standard with Ruby, but you should check for the latest version on the RAA.

It often happens that people ask questions on ruby-talk that are easily answered with one of the above (I've probably done it about five times now...). Every Ruby programmer needs to know how to use these tools. They will help your programs to run right first time!

### Websites

[Ruby Central]
  Ruby Central has a good links section and generally contains some interesting material.

[The Ruby Homepage]
  A bit of everything. As of early 2003 (not yet at time of writing), the new site features much-improved presentation and links to other resources.

[The RAA]
  The Ruby Application Archive. At time of writing, there are 766 packages available for download. Some very important packages are listed in the next section.

[The ''ruby-talk'' website]
  Here you can browse and search the ruby-talk archives. These contain a wealth of information that can likely help you.

[The Ruby-Doc Project]
  Several projects have existed with names varying on "ruby doc". This one collects documentation and offers a web query interface to ri and The Pickaxe.

### Important Packages

Programming often involves doing things that the language can't do natively - XML, database, web, etc. If you're just starting out with Ruby, but have some specific tasks in mind, there's probably something for you on the RAA (or perhaps bundled with your Ruby distribution).

The following packages are examined in Ruby Developer's Guide:

- For database programming - DBI.
- For XML-related tasks - REXML. There are others, but this one will probably do what you want, in a nice Ruby style.
- For web services and distributed Ruby - XML-RPC, SOAP4R and DRb.
- For web programming - mod_ruby, eruby
- For GUI programming - Ruby/GTK, FXRuby

Other packages in mature states and common use:

- Test::Unit for unit testing
- Log4r for logging
- Win32OLE for Windows automation
- RDoc for API document generation from source code

Every beginner should at least know about these packages, so that they know they have somewhere to turn when these sort of tasks come up.

## Participating in the Ruby Community

The Ruby Community is generally understood to be that body of people who do one or more of the following things:

- participate in ruby-talk or on IRC
- create and/or maintain packages in the Ruby Application Archive
- make an original and miscellaneous contribution to Ruby advocacy (for example, http://www.rubyxml.org or http://www.rubydoc.org)

The following sections detail these and other community resources, and give guidelines on their use.

### The Mailing List and Newsgroup

ruby-talk is the name of a mailing list (`ruby-talk@ruby-lang.org`) and a newsgroup (`comp.lang.ruby`) that, thanks to a small piece of Ruby code, are actually the same thing. That is, messages on the mailing list appear on the newsgroup and vice versa.

More information can be found in the comp.lang.ruby FAQ (included in the bundle), but I'll make a few comments here.

The ruby-talk community has been noticably friendly in general, including its treatment of people asking questions that are easily answered elsewhere. However, it is basic netiquette to do some research before posting. In the case of Ruby, this research should consist of examining ri and The Pickaxe for technical information. If your question is more theoretical, ask yourself whether it's likely to have been asked before. If a simple search of the archives turns up nothing, then chances are your question is unique; if it turns up not-quite-relevant material, you at least will have an idea of what has been discussed before, and will likely produce a more educated post than you would have otherwise.

Discussion on ruby-talk is sometimes quite general in nature, and occasionally wanders off-topic. That's OK, since it seems that many regular posters have a broad or deep experience, and good communication skills, so the discussion is often interesting and useful. Since Ruby contains good features from many languages, we often learn a thing or two about other languages as well.

ruby-talk has its own webpage: http://www.ruby-talk.org. On this page, you can browse (through a nice web interface) and search the archives, as well as join the list and get help on it. It's a terrific webpage, and my advice to budding Rubyists is to use it (or a newsreader) to "lurk" for a while before posting, unless you have a specific question. Just browsing the recent entries will inform you of recent announcements (software, webpages, etc.), important questions, and general Ruby musings, so that you gain an insight into what people are doing with Ruby and how they are doing it.

Every week, a "Ruby Weekly News" is posted that summarises announcements and interesting threads on ruby-talk for the week. This can be seen [here].

### IRC

There is an IRC channel where Rubyists gather. The channel is populated most of the time because there are Rubyists in so many timezones.

The IRC server is: irc.openprojects.net. The channel is: #ruby-lang

Newbies should get stuck into IRC: they'll often get a quick response, and the conversational style allows feedback without clogging the mailing list.

### The Wiki

The Wiki is located at http://www.rubygarden.org/ruby. Briefly, a Wiki is a set of webpages that can be edited by anybody, using a special markup language that is greatly simpler than HTML. It is an interesting concept. I encourage all Rubyists to browse the Wiki and, where comfortable, make changes.

Being a kind of chaos, the Wiki contains a lot of information but little enforced organisation. Hence, it is sometimes like a bulletin board where people simply post their point of view, and sometimes like a collection of half-sorted information. It takes a bit of getting used to, but it is a valuable resource.

The Wiki is ideally suited for creating small documents, like this one, because the formatting is simple, and hosting is taken care of. The other option, editing my own HTML and finding somewhere to host it, is no real option at all. It can also be useful for tracking projects, but there are perhaps better ways to do that.

### The RAA

The Ruby Application Archive (RAA) is the repository of user-contributed code (libraries and applications). Containing 766 projects at time of writing, this site is naturally an important community resource. Many crucial libraries live there, many merely useful ones, and many experimental ones. If you find something you want that is incomplete, think of it as an opportunity to contribute.

It is a great place to find sample code if you need some to study.

### User Groups

See if there is a Ruby Users Group in your area. A large list of such groups is maintained on the Wiki at RubyUserGroups. Some groups only have one or two members; if so, get in touch with them anyway and add your name. Once a critical mass is formed, you can enjoy monthly meetings, and perhaps collaborate on projects.

## Conclusion

If you are learning Ruby and need some help, or just want to soak up some knowledge and experience, seek out fellow Rubyists in user groups, on IRC and on ruby-talk - whatever mix suits your preferences.

Before you do, however, read at least some of The Pickaxe and browse some other resources (newcomer's guide, FAQ, tutorials: all included in the bundle). They are there for your benefit! If you want a paperback book to help you in the beginning, choose between The Pickaxe and Teach Yourself Ruby in 21 Days, depending on your skill level.

Being able to use ri and irb is very important. The first is for reference, the second for experimentation. Very important indeed.

It may be possible to gain advanced knowledge of Ruby without reading The Ruby Way, but you will thank yourself for owning it, especially if you want to know how to use Ruby to accomplish all sorts of tasks. For more specialised tasks, be sure to check out Ruby Developer's Guide.

Community participation - even passive - will boost your familiarity with the language as you see problems and solutions being discussed, and eventually presented on the RAA. Active participation, when you're ready, will offer opportunities to learn through contribution, which is ultimately what the prosperity of Ruby thrives on.

Good luck!