diff --git a/src/ruby/README.md b/src/ruby/README.md
index 23aec2b20afe1f21dffa7060ebddd8de11fa415e..7f7558dc6770b56d3bc42aee30c03009d464393a 100755
--- a/src/ruby/README.md
+++ b/src/ruby/README.md
@@ -1,64 +1,63 @@
-Ruby for GRPC
-=============
+gRPC Ruby
+=========
 
-LAYOUT
-------
+A Ruby implementation of gRPC, Google's RPC library.
 
-Directory structure is the recommended layout for [ruby extensions](http://guides.rubygems.org/gems-with-extensions/)
 
- * ext: the extension code
- * lib: the entrypoint grpc ruby library to be used in a 'require' statement
- * test: tests
+INSTALLATION PREREQUISITES
+--------------------------
 
+This requires Ruby 2.x, as the rpc api surface uses keyword args.
 
-DEPENDENCIES
-------------
 
+INSTALLING
+----------
 
-* Extension
+- Install the gRPC core library
+TODO: describe this, once the core distribution mechanism is defined.
 
-The extension can be built and tested using
-[rake](https://rubygems.org/gems/rake).  However, the rake-extensiontask rule
-is not supported on older versions of rubygems, and the necessary version of
-rubygems.
+$ gem install grpc
 
-This is resolved by using [RVM](https://rvm.io/) instead; install a single-user
-ruby environment, and develop on the latest stable version of ruby (2.1.5).
 
+Installing from source
+----------------------
 
-INSTALLATION PREREQUISITES
---------------------------
-
-Install RVM
+- Build or Install the gRPC core
+E.g, from the root of the grpc [git repo](https://github.com/google/grpc)
+$ cd ../..
+$ make && sudo make install
 
+- Install Ruby 2.x. Consider doing this with [RVM](http://rvm.io), it's a nice way of controlling
+  the exact ruby version that's used.
 $ command curl -sSL https://rvm.io/mpapis.asc | gpg --import -
 $ \curl -sSL https://get.rvm.io | bash -s stable --ruby
 $
 $ # follow the instructions to ensure that your're using the latest stable version of Ruby
 $ # and that the rvm command is installed
-$
-$ gem install bundler  # install bundler, the standard ruby package manager
 
-HACKING
--------
+- Install [bundler](http://bundler.io/)
+$ gem install bundler
 
-The extension can be built and tested using the Rakefile.
+- Finally, install grpc ruby locally.
+$ cd <install_dir>
+$ bundle install
+$ rake  # compiles the extension, runs the unit tests, see rake -T for other options
 
-$ # create a workspace
-$ git5 start <your-git5-branch> net/grpc
-$
-$ # build the C library and install it in $HOME/grpc_dev
-$ <google3>/net/grpc/c/build_gyp/build_grpc_dev.sh
-$
-$ # build the ruby extension and test it.
-$ cd google3_dir/net/grpc/ruby
-$ rake
 
-Finally, install grpc ruby locally.
+CONTENTS
+--------
 
-$ cd <this_dir>
-$
-$ # update the Gemfile, modify the line beginning # gem 'beefcake' to refer to
-$ # the patched beefcake dir
-$
-$ bundle install
+Directory structure is the layout for [ruby extensions](http://guides.rubygems.org/gems-with-extensions/)
+
+ * ext: the extension code
+ * lib: the entrypoint grpc ruby library to be used in a 'require' statement
+ * spec: tests
+ * bin: example gRPC clients and servers, e.g,
+```ruby
+# client
+stub = Math::Math::Stub.new('my.test.math.server.com:8080')
+req = Math::DivArgs.new(dividend: 7, divisor: 3)
+logger.info("div(7/3): req=#{req.inspect}")
+resp = stub.div(req, INFINITE_FUTURE)
+logger.info("Answer: #{resp.inspect}")
+```