diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+
+Web.Envelope
+============
+
+[![Hackage](https://img.shields.io/hackage/v/envelope.svg)](https://hackage.haskell.org/package/envelope) [![Build Status](https://secure.travis-ci.org/cdepillabout/envelope.svg)](http://travis-ci.org/cdepillabout/envelope)
+
+
+This module exports an `Envelope` type that can be used to wrap reponses from a JSON REST API.  It provides a successful `Success` response, and a failure `Err` response.
+
+Here is a small demonstration of returning a success response:
+
+```haskell
+>>> import qualified Data.ByteString.Lazy.Char8 as C8
+>>> import Data.Aeson (decode, encode)
+>>> let successEnvelope = toSuccessEnvelope 3 :: Envelope Text Int
+>>> C8.putStrLn $ encode successEnvelope
+{"data":3}
+>>> decode "{\"data\":3}" :: Maybe (Envelope Text Int)
+Just (EnvelopeSuccess (Success 3))
+```
+
+Your data gets wrapped in an object with a single `"data"` field:
+
+```json
+{
+    "data": 3
+}
+```
+
+Now lets look at how an error response is encoded and decoded.  It is encoded
+as an object with two members: @\"extra\"@ and @\"error\"@.
+
+```haskell
+>>> let errorEnvelope = toErrEnvelope "DB_ERROR" "there was an error in the database" :: Envelope String Int
+>>> C8.putStrLn $ encode errorEnvelope
+{"extra":"there was an error in the database","error":"DB_ERROR"}
+>>> decode "{\"extra\":\"there was an error in the database\",\"error\":\"DB_ERROR\"}" :: Maybe (Envelope String Int)
+Just (EnvelopeErr (Err {errErr = "DB_ERROR", errExtra = Just "there was an error in the database"}))
+```
+
+Your error type and extra message get wrapped in an object:
+
+```json
+{
+    "extra": "there was an error in the database",
+    "error": "DB_ERROR"
+}
+```
diff --git a/envelope.cabal b/envelope.cabal
--- a/envelope.cabal
+++ b/envelope.cabal
@@ -1,5 +1,5 @@
 name:                envelope
-version:             0.2.0.0
+version:             0.2.0.1
 synopsis:            Defines generic 'Envelope' type to wrap reponses from a JSON API.
 description:         Please see README.md
 homepage:            https://github.com/cdepillabout/envelope#readme
@@ -10,7 +10,7 @@
 copyright:           2016 Dennis Gosnell
 category:            Web
 build-type:          Simple
--- extra-source-files:
+extra-source-files:  README.md
 cabal-version:       >=1.10
 
 library