README.md in tjson-0.0.0 vs README.md in tjson-0.1.0

@@ -1,11 +1,20 @@
-# TJSON for Ruby
+# TJSON for Ruby [![Gem Version][gem-image]][gem-link] [![Build Status][build-image]][build-link] [![Code Climate][codeclimate-image]][codeclimate-link] [![MIT licensed][license-image]][license-link]
 
 A Ruby implementation of TJSON: Tagged JSON with Rich Types.
 
 https://www.tjson.org
 
+[gem-image]: https://badge.fury.io/rb/tjson.svg
+[gem-link]: https://rubygems.org/gems/tjson
+[build-image]: https://secure.travis-ci.org/tjson/tjson-ruby.svg?branch=master
+[build-link]: https://travis-ci.org/tjson/tjson-ruby
+[codeclimate-image]: https://codeclimate.com/github/tjson/tjson-ruby.svg?branch=master
+[codeclimate-link]: https://codeclimate.com/github/tjson/tjson-ruby
+[license-image]: https://img.shields.io/badge/license-MIT-blue.svg
+[license-link]: https://github.com/tjson/tjson-ruby/blob/master/LICENSE.txt
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -20,10 +29,55 @@
 
     $ gem install tjson
 
 ## Usage
 
-Coming soon!
+### Parsing
+
+To parse a TJSON document, use the `TJSON.parse` method:
+
+```ruby
+>> TJSON.parse('{"s:foo":"s:bar"}')
+=> {"foo"=>"bar"}
+```
+
+The following describes how TJSON types map onto Ruby types during parsing:
+
+ * **UTF-8 Strings**: parsed as Ruby `String` with `Encoding::UTF_8`
+ * **Binary Data**: parsed as Ruby `String` with `Encoding::ASCII_8BIT` (a.k.a. `Encoding::BINARY`)
+ * **Integers**: parsed as Ruby `Integer` (Fixnum or Bignum)
+ * **Floats** (i.e. JSON number literals): parsed as Ruby `Float`
+ * **Timestamps**: parsed as Ruby `Time`
+ * **Arrays**: parsed as `TJSON::Array` (a subclass of `::Array`)
+ * **Objects**: parsed as `TJSON::Object` (a subclass of `::Hash`)
+
+### Generating
+
+To generate TJSON from Ruby objects, use the `TJSON.generate` method:
+
+```ruby
+>> puts TJSON.generate({"foo" => "bar" })
+{"s:foo":"s:bar"}
+```
+
+The `TJSON.generate` method will call `#to_tjson` on any objects which are not
+one of Ruby's core types. You can implement this method on classes you wish to
+serialize as TJSON, although it MUST output tagged strings for encoding TJSON
+types such as UTF-8 strings or binary data.
+
+### TJSON::Binary
+
+The `TJSON::Binary` module contains a set of helper methods for serializing
+binary data in various different encodings:
+
+```ruby
+>> TJSON::Binary.base16("Hello, world!")
+=> "b16:48656c6c6f2c20776f726c6421"
+>> TJSON::Binary.base32("Hello, world!")
+=> "b32:jbswy3dpfqqho33snrscc"
+>> TJSON::Binary.base64("Hello, world!")
+=> "b64:SGVsbG8sIHdvcmxkIQ"
+```
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/tjson/tjson-ruby