diff --git a/Quickson.cabal b/Quickson.cabal
--- a/Quickson.cabal
+++ b/Quickson.cabal
@@ -1,9 +1,6 @@
-name:              quickson
-version:           1.0
-Build-Type:        Simple
-cabal-version:     >= 1.2
 Name:		       Quickson
-Version:	       0.1
+Version:	       0.1.1
+Build-Type:        Simple
 Cabal-Version:     >= 1.2
 License:	       BSD3
 License-File:      LICENSE
diff --git a/src/Data/Quickson.hs b/src/Data/Quickson.hs
--- a/src/Data/Quickson.hs
+++ b/src/Data/Quickson.hs
@@ -1,7 +1,19 @@
 {-# LANGUAGE OverloadedStrings #-}
 
-module Data.Quickson where
+module Data.Quickson
+    (
+    -- * How to use this library
+    -- $use
 
+    -- * Syntax
+    -- $syntax
+      Quickson(..)
+    , quicksonParse
+    , quicksonExecute
+    , quickson
+    ) where
+
+
 import           Control.Monad
 import           Control.Applicative
 import           Data.Aeson
@@ -44,9 +56,41 @@
     look v (k,False,qq) = v.:k >>= drill qq
 
 
--- | Perform a JSON extraction
+-- | Perform a JSON extraction, returning either an error description
+--   or a parsed data structure
 quickson :: FromJSON a => BS.ByteString -> BS.ByteString -> Either String a
 quickson structureSpec bs = do
     val <- eitherDecodeStrict bs
     query <- quicksonParse structureSpec
     quicksonExecute query val
+
+
+-- $use
+--
+-- Quickson exports a function `quickson` which enables you to perform quick
+-- extractions of JSON data using Aeson.
+--
+-- Aeson's type machinery allows decoding of complex data structures using
+-- just the 'decode' function, however, JSON object lookups cannot be encoded
+-- using the type system alone. Quickson helps by doing the lookups for you
+-- so that the type system can do the rest. For example, say you have a JSON
+-- document as such:
+--
+-- > { "name": "bob", "age": 25, "hobbies": [{"name": "Tennis"}] }
+--
+-- And you'd like to turn this into a `(String, Maybe Int, [String])` with
+-- minimal fuss:
+--
+-- > >>> type Hobbyist = (String, Maybe Int, [String])
+-- > >>> let eitherResult = quickson "{name,age?,hobbies:[{name}]}" jsonDoc :: Either String Hobbyist
+-- > Right ("bob",Just 25,["Tennis"])
+--
+-- So the structure specification is just to remove the objects so that the type
+-- system can do the rest.
+
+-- $syntax
+-- - Top level objects must be [] or {}
+-- - Lookup: {key}
+-- - Optional lookup: {key?} (yielding Maybe a)
+-- - List: []
+--