From 094b7e864fa9601d65ccc6ed5a4aa49cbbbf1d0b Mon Sep 17 00:00:00 2001
From: Tim Craft <mail@timcraft.com>
Date: Fri, 16 Nov 2012 23:16:45 +0000
Subject: [PATCH] Update readme

---
 README.md | 59 +++++++++++++++++++++++++++++++++----------------------
 1 file changed, 36 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 53025bcb..eb2770e2 100644
--- a/README.md
+++ b/README.md
@@ -2,50 +2,63 @@ A simple wrapper for the [Nexmo](http://nexmo.com/) API
 =======================================================
 
 
-Requirements
-------------
-
-Ruby 1.9; Ruby 1.8 is not currently supported.
-
-
 Installation
 ------------
 
-    gem install nexmo
+    $ gem install nexmo
 
 
 Quick Start
 -----------
 
+Use the `send_message!` for a "fire and forget" approach to sending a message:
+
 ```ruby
 require 'nexmo'
 
 nexmo = Nexmo::Client.new('...API KEY...', '...API SECRET...')
 
-response = nexmo.send_message({
-  from: 'RUBY',
-  to: '...NUMBER...',
-  text: 'Hello world'
-})
-
-if response.success?
-  puts "Sent message: #{response.message_id}"
-elsif response.failure?
-  raise response.error
-end
+nexmo.send_message!({:to => '...NUMBER...', :from => 'Ruby', :text => 'Hello world'})
 ```
 
+This method call returns the message id if the message was sent successfully,
+or raises an exception if there was an error.
+
+
+Handling Errors
+---------------
+
+For more robust error handling use the `send_message` method instead.
+This returns the HTTP response wrapped in a `Nexmo::Response` object.
+
+
+JSON Implementation
+-------------------
+
+The "json" library is used by default. This is available in the Ruby 1.9
+standard library, and as a gem for Ruby 1.8.
+
+You can specify which implementation you wish to use explicitly when
+constructing a client object. For example, here is how you would use
+[oj](https://rubygems.org/gems/oj):
+
+```ruby
+require 'nexmo'
+require 'oj'
+
+nexmo = Nexmo::Client.new('...API KEY...', '...API SECRET...', :json => Oj)
+```
+
+Ditto for MultiJSON, or anything that is compatible with the interface
+of the default implementation.
+
 
 Troubleshooting
 ---------------
 
-Phone numbers should be specified in international format.
+Remember that phone numbers should be specified in international format.
 
 The Nexmo documentation contains a [list of error codes](http://nexmo.com/documentation/index.html#response_code)
 which may be useful if you have problems sending a message.
 
-
-Bugs/Issues
------------
-
 Please report all bugs/issues via the GitHub issue tracker.