diff --git a/.gitignore b/.gitignore
index c1e0dafa..184c6dcf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,3 +19,4 @@ rdoc
 pkg
 
 ## PROJECT::SPECIFIC
+examples/wynn.rb
\ No newline at end of file
diff --git a/README.markdown b/README.markdown
index 01bcd78b..d0e9edfd 100644
--- a/README.markdown
+++ b/README.markdown
@@ -1,9 +1,61 @@
-# linkedin
+# LinkedIn
+
+Ruby wrapper for the [LinkedIn API](http://developer.linkedin.com). Heavily inspired by [John Nunemaker's](http://github.com/jnunemaker) [Twitter gem](http://github.com/jnunemaker/twitter), the LinkedIn gem provides an easy-to-use wrapper for LinkedIn's Oauth/XML APIs.
+
+## Installation
+
+    sudo gem install gemcutter
+    gem tumble
+    sudo gem install linkedin
+    
+## Usage
+
+### Authenticate
+
+LinkedIn's API uses Oauth for authentication. Luckily, the LinkedIn gem hides most of the gory details from you.
+
+    require 'rubygems'
+    require 'linkedin'
+
+    # get your api keys at https://www.linkedin.com/secure/developer
+    client = LinkedIn::Client.new('your_consumer_key', 'your_consumer_secret')
+    rtoken = client.request_token.token
+    rsecret = client.request_token.secret
+
+    # to test from your desktop, open the following url in your browser
+    # and record the pin it gives you
+    client.request_token.authorize_url
+    => "https://api.linkedin.com/uas/oauth/authorize?oauth_token=<generated_token>"
+
+    # then fetch your access keys
+    client.authorize_from_request(rtoken, rsecret, pin)
+    => ["OU812", "8675309"] # <= save these for future requests
+
+    # or authorize from previously fetched access keys
+    c.authorize_from_access("OU812", "8675309")
+
+    # you're now free to move about the cabin, call any API method
+
+### Profile examples
+
+    # get the profile for the authenticated user
+    client.profile
+
+    # get a profile for someone found in network via ID
+    client.profile(:id => 'gNma67_AdI')
+
+    # get a profile for someone via their public profile url
+    client.profile(:url => 'http://www.linkedin.com/in/netherland')
+    
+
+
+More examples in the [examples folder](http://github.com/pengwynn/linkedin/blob/master/examples).
+
 
-Ruby wrapper for the [LinkedIn API](http://developer.linkedin.com)
 
 ## TODO
-* Implement Search, Status, Invitation APIs
+
+* Implement Messaging APIs
 
 ## Note on Patches/Pull Requests
  
diff --git a/examples/authenticate.rb b/examples/authenticate.rb
new file mode 100644
index 00000000..bfbbb819
--- /dev/null
+++ b/examples/authenticate.rb
@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'linkedin'
+
+# get your api keys at https://www.linkedin.com/secure/developer
+client = LinkedIn::Client.new('your_consumer_key', 'your_consumer_secret')
+rtoken = client.request_token.token
+rsecret = client.request_token.secret
+
+# to test from your desktop, open the following url in your browser
+# and record the pin it gives you
+client.request_token.authorize_url
+=> "https://api.linkedin.com/uas/oauth/authorize?oauth_token=<generated_token>"
+
+# then fetch your access keys
+client.authorize_from_request(rtoken, rsecret, pin)
+=> ["OU812", "8675309"] # <= save these for future requests
+
+# or authorize from previously fetched access keys
+c.authorize_from_access("OU812", "8675309")
+
+# you're now free to move about the cabin, call any API method 
\ No newline at end of file
diff --git a/examples/network.rb b/examples/network.rb
new file mode 100644
index 00000000..2d19ae70
--- /dev/null
+++ b/examples/network.rb
@@ -0,0 +1,12 @@
+# AUTHENTICATE FIRST found in examples/authenticate.rb
+
+# client is a LinkedIn::Client
+
+# get network updates for the authenticated user
+client.network_updates
+
+# get profile picture changes
+client.network_updates(:type => 'PICT')
+
+# view connections for the currently authenticated user
+client.connections
\ No newline at end of file
diff --git a/examples/profile.rb b/examples/profile.rb
new file mode 100644
index 00000000..c1786cdf
--- /dev/null
+++ b/examples/profile.rb
@@ -0,0 +1,14 @@
+# AUTHENTICATE FIRST found in examples/authenticate.rb
+
+# client is a LinkedIn::Client
+
+# get the profile for the authenticated user
+client.profile
+
+# get a profile for someone found in network via ID
+client.profile(:id => 'gNma67_AdI')
+
+# get a profile for someone via their public profile url
+client.profile(:url => 'http://www.linkedin.com/in/netherland')
+
+
diff --git a/examples/status.rb b/examples/status.rb
new file mode 100644
index 00000000..d23ebe5a
--- /dev/null
+++ b/examples/status.rb
@@ -0,0 +1,9 @@
+# AUTHENTICATE FIRST found in examples/authenticate.rb
+
+# client is a LinkedIn::Client
+
+# update status for the authenticated user
+client.update_status('is playing with the LinkedIn Ruby gem')
+
+# clear status for the currently logged in user
+client.clear_status