diff --git a/README.rdoc b/README.rdoc
index 07d5652..cff4f67 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -1,53 +1,47 @@
= FakeWeb
-A Helper for Faking Web Requests
+FakeWeb is a helper for faking web requests. It works at a global level, without
+modifying code or writing extensive stubs.
= Examples
- require 'test/unit'
- require 'fake_web'
- require 'open-uri'
-
- class FakeWebExampleTest < Test::Unit::TestCase
- def test_request
- FakeWeb.register_uri('http://example.com/test_me', :string => "Hello World!")
- content = Net::HTTP.get(URI.parse('http://example.com/test_me'))
- assert_equal "Hello World!", content
- end
-
- def test_request_with_response
- FakeWeb.register_uri('http://www.google.com/', :response => `curl -is http://www.google.com/`)
- Net::HTTP.start('www.google.com') do |req|
- response = req.get('/')
- if response.code == 200
- assert_equal "OK", response.message
- assert response.body.include?('
Google')
- elsif response.code == 302
- # Google redirects foreign sites to ccTLDs.
- assert_equal "Found", response.message
- assert response.body.include?('The document has moved')
- end
- end
- end
-
- def test_request_with_custom_status
- FakeWeb.register_uri('http://example.com/', :string => "Nothing to be found 'round here",
- :status => ['404', 'Not Found'])
- Net::HTTP.start('example.com') do |req|
- response = req.get('/')
- assert_equal "404", response.code
- assert_equal "Not Found", response.message
- assert_equal "Nothing to be found 'round here", response.body
- end
- end
-
- def test_open_uri
- FakeWeb.register_uri('http://example.com/', :string => "Hello, World!")
- content = open('http://example.com/').string
- assert_equal "Hello, World!", content
- end
+== Using a string response
+
+ FakeWeb.register_uri("http://example.com/test1", :string => "Hello World!")
+
+ Net::HTTP.get(URI.parse('http://example.com/test1'))
+ => "Hello World!"
+
+ Net::HTTP.get(URI.parse('http://example.com/test2'))
+ => FakeWeb is bypassed and the response from a real request is returned
+
+== Replaying a recorded response
+
+ page = `curl -is http://www.google.com/`
+ FakeWeb.register_uri('http://www.google.com/', :response => page)
+
+ Net::HTTP.get(URI.parse('http://www.google.com/'))
+ # => Full response, including headers
+
+== Adding a custom status to the response
+
+ FakeWeb.register_uri('http://example.com/', :string => "Nothing to be found 'round here",
+ :status => ["404", "Not Found"])
+
+ Net::HTTP.start('example.com') do |req|
+ response = req.get('/')
+ response.code # => "404"
+ response.message # => "Not Found"
+ response.body # => "Nothing to be found 'round here"
end
+== Requesting with OpenURI
+
+ FakeWeb.register_uri('http://example.com/', :string => "Hello, World!")
+
+ open('http://example.com/').string
+ => "Hello, World!"
+
= Description