README.md in socketry-0.1.0 vs README.md in socketry-0.2.0

@@ -17,39 +17,76 @@
 timeout support that can be used with any multithreaded Ruby app. That said,
 Socketry can also be used to provide asynchronous I/O with [Celluloid::IO].
 
 [Celluloid::IO]: https://github.com/celluloid/celluloid-io
 
+## Motivation
+
+By default, Ruby sockets do not provide a built-in timeout mechanism. The only
+timeout mechanism provided by the language leverages [timeout.rb], which uses
+[unsafe multithreaded behaviors] to implement timeouts.
+
+While Socketry provides a synchronous, blocking API similar to Ruby's own
+`TCPSocket` and `UDPSocket` classes, behind the scenes it uses non-blocking I/O
+to implement thread-safe timeouts.
+
+Highly modular and pluggable, Socketry also provides the flexibility to
+seamlessly leverage [Celluloid::IO] for event-driven I/O.
+
+[timeout.rb]: http://ruby-doc.org/stdlib-2.3.1/libdoc/timeout/rdoc/Timeout.html
+[unsafe multithreaded behaviors]: http://blog.headius.com/2008/02/ruby-threadraise-threadkill-timeoutrb.html
+[Celluloid::IO]: https://github.com/celluloid/celluloid-io
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'socketry'
+gem "socketry"
 ```
 
 And then execute:
 
     $ bundle
 
 Or install it yourself as:
 
     $ gem install socketry
 
-## Usage
+## Basic Usage
 
-TODO: Coming soon!
+Below is a basic example of how to use Socketry to make an HTTPS request:
 
+```ruby
+require "socketry"
+
+socket = Socketry::SSL::Socket.connect("github.com", 443)
+socket.writepartial("GET / HTTP/1.0\r\nHost: github.com\r\n\r\n")
+p socket.readpartial(1024)
+```
+
+[TCP], [UDP], and [SSL] servers and sockets also available.
+
+[TCP]: https://github.com/socketry/socketry/wiki/TCP
+[UDP]: https://github.com/socketry/socketry/wiki/UDP
+[SSL]: https://github.com/socketry/socketry/wiki/SSL
+
+## Documentation
+
+[Please see the Socketry wiki](https://github.com/socketry/socketry/wiki)
+for more detailed documentation and usage notes.
+
+[YARD API documentation](http://www.rubydoc.info/gems/socketry/)
+is also available.
+
 ## Contributing
 
 * Fork this repository on github
 * Make your changes and send us a pull request
 * If we like them we'll merge them
 * If we've accepted a patch, feel free to ask for commit access
 
 ## License
 
-Copyright (c) 2016 Tony Arcieri
-
-Distributed under the MIT License. See
+Copyright (c) 2016 Tony Arcieri. Distributed under the MIT License. See
 [LICENSE.txt](https://github.com/socketry/socketry/blob/master/LICENSE.txt)
 for further details.