diff --git a/README.md b/README.md
index 2dd38d13..6699a326 100644
--- a/README.md
+++ b/README.md
@@ -28,9 +28,12 @@ Here is the list of known external adapters:
 It also includes a Rack adapter for hitting loaded Rack applications through
 Rack::Test, and a Test adapter for stubbing requests by hand.
 
-## API documentation
+## Documentation
 
-Available at [rubydoc.info](http://www.rubydoc.info/gems/faraday).
+* [Faraday API RubyDoc](http://www.rubydoc.info/gems/faraday)
+* [Middleware](./docs/middleware)
+  * [Middleware Environment](./docs/middleware/env.md)
+* [Testing](./docs/adapters/testing.md)
 
 ## Usage
 
@@ -290,41 +293,6 @@ Faraday is intended to be a generic interface between your code and the adapter.
 
 When that happens, you can pass a block when specifying the adapter to customize it. The block parameter will change based on the adapter you're using. See below for some examples.
 
-## Using Faraday for testing
-
-```ruby
-# It's possible to define stubbed request outside a test adapter block.
-stubs = Faraday::Adapter::Test::Stubs.new do |stub|
-  stub.get('/tamago') { |env| [200, {}, 'egg'] }
-end
-
-# You can pass stubbed request to the test adapter or define them in a block
-# or a combination of the two.
-test = Faraday.new do |builder|
-  builder.adapter :test, stubs do |stub|
-    stub.get('/ebi') { |env| [ 200, {}, 'shrimp' ]}
-  end
-end
-
-# It's also possible to stub additional requests after the connection has
-# been initialized. This is useful for testing.
-stubs.get('/uni') { |env| [ 200, {}, 'urchin' ]}
-
-resp = test.get '/tamago'
-resp.body # => 'egg'
-resp = test.get '/ebi'
-resp.body # => 'shrimp'
-resp = test.get '/uni'
-resp.body # => 'urchin'
-resp = test.get '/else' #=> raises "no such stub" error
-
-# If you like, you can treat your stubs as mocks by verifying that all of
-# the stubbed calls were made. NOTE that this feature is still fairly
-# experimental: It will not verify the order or count of any stub, only that
-# it was called once during the course of the test.
-stubs.verify_stubbed_calls
-```
-
 ## Supported Ruby versions
 
 This library aims to support and is [tested against][travis] the following Ruby
diff --git a/docs/adapters/testing.md b/docs/adapters/testing.md
new file mode 100644
index 00000000..ecaa4597
--- /dev/null
+++ b/docs/adapters/testing.md
@@ -0,0 +1,59 @@
+# Testing
+
+The built-in Faraday Test adapter lets you define stubbed HTTP requests. This can
+be used to mock out network services in an application's unit tests.
+
+The easiest way to do this is to create the stubbed requests when initializing
+a `Faraday::Connection`. Stubbing a request by path yields a block with a
+`Faraday::Env` object. The stub block expects an Array return value with three
+values: an Integer HTTP status code, a Hash of key/value headers, and a
+response body.
+
+```ruby
+conn = Faraday.new do |builder|
+  builder.adapter :test do |stub|
+    stub.get('/ebi') do |env|
+      [
+        200, # status code
+        {
+          'Content-Type': 'text/plain',
+        }, # headers
+        'shrimp' # response body
+      ]
+    end
+  end
+end
+```
+
+You can define the stubbed requests outside of the test adapter block:
+
+```ruby
+stubs = Faraday::Adapter::Test::Stubs.new do |stub|
+  stub.get('/tamago') { |env| [200, {}, 'egg'] }
+end
+```
+
+This Stubs instance can be passed to a new Connection:
+
+```ruby
+conn = Faraday.new do |builder|
+  builder.adapter :test, stubs do |stub|
+    stub.get('/ebi') { |env| [ 200, {}, 'shrimp' ]}
+  end
+end
+```
+
+It's also possible to stub additional requests after the connection has been
+initialized. This is useful for testing.
+
+```ruby
+stubs.get('/uni') { |env| [ 200, {}, 'urchin' ]}
+```
+
+Finally, you can treat your stubs as mocks by verifying that all of the stubbed
+calls were made. NOTE: this feature is still fairly experimental. It will not
+verify the order or count of any stub.
+
+```ruby
+stubs.verify_stubbed_calls
+```
diff --git a/docs/middleware/README.md b/docs/middleware/README.md
new file mode 100644
index 00000000..495fadb7
--- /dev/null
+++ b/docs/middleware/README.md
@@ -0,0 +1,24 @@
+# Middleware Usage
+
+A `Faraday::Connection` uses a `Faraday::RackBuilder` to assemble a
+Rack-inspired middleware stack for making HTTP requests. Each middleware runs
+and passes an Env object around to the next one. After the final middleware has
+run, Faraday will return a `Faraday::Response` to the end user.
+
+## Middleware Types
+
+**Request middleware** can modify Request details before the Adapter runs. Most
+middleware set Header values or transform the request body based on the
+content type.
+
+* `BasicAuthentication` sets the `Authorization` header to the `user:password`
+base64 representation.
+* `Multipart` converts a `Faraday::Request#body` hash of key/value pairs into a
+multipart form request.
+* `UrlEncoded` converts a `Faraday::Request#body` hash of key/value pairs into a url-
+encoded request body.
+
+**Adapters** make requests. TBD
+
+* `Retry` automatically retries requests that fail due to intermittent client
+or server errors (such as network hiccups).
diff --git a/docs/middleware/env.md b/docs/middleware/env.md
new file mode 100644
index 00000000..28748365
--- /dev/null
+++ b/docs/middleware/env.md
@@ -0,0 +1,3 @@
+# Faraday Env
+
+Faraday loves the environment.