diff --git a/Aws/Aws.hs b/Aws/Aws.hs
--- a/Aws/Aws.hs
+++ b/Aws/Aws.hs
@@ -107,11 +107,21 @@
       => Configuration -> HTTP.Manager -> r -> IO (Response (ResponseMetadata a) a)
 aws = unsafeAws
 
+awsRef :: (Transaction r a
+       , ConfigurationFetch (Info r))
+      => Configuration -> HTTP.Manager -> IORef (ResponseMetadata a) -> r -> IO a
+awsRef = unsafeAwsRef
+
 simpleAws :: (Transaction r a
              , ConfigurationFetch (Info r))
             => Configuration -> r -> IO (Response (ResponseMetadata a) a)
 simpleAws cfg request = HTTP.withManager $ \manager -> liftIO $ aws cfg manager request
 
+simpleAwsRef :: (Transaction r a
+             , ConfigurationFetch (Info r))
+            => Configuration -> IORef (ResponseMetadata a) -> r -> IO a
+simpleAwsRef cfg metadataRef request = HTTP.withManager $ \manager -> liftIO $ awsRef cfg manager metadataRef request
+
 unsafeAws
   :: (ResponseConsumer r a,
       Monoid (ResponseMetadata a),
@@ -119,18 +129,28 @@
       ConfigurationFetch (Info r)) =>
      Configuration -> HTTP.Manager -> r -> IO (Response (ResponseMetadata a) a)
 unsafeAws cfg manager request = do
+  metadataRef <- newIORef mempty
+  resp <- attemptIO (id :: E.SomeException -> E.SomeException) $
+            unsafeAwsRef cfg manager metadataRef request
+  metadata <- readIORef metadataRef
+  return $ Response metadata resp
+
+unsafeAwsRef
+  :: (ResponseConsumer r a,
+      Monoid (ResponseMetadata a),
+      SignQuery r,
+      ConfigurationFetch (Info r)) =>
+     Configuration -> HTTP.Manager -> IORef (ResponseMetadata a) -> r -> IO a
+unsafeAwsRef cfg manager metadataRef request = do
   sd <- signatureData <$> timeInfo <*> credentials $ cfg
   let info = configurationFetch cfg
   let q = signQuery request info sd
   logger cfg Debug $ T.pack $ "String to sign: " ++ show (sqStringToSign q)
   let httpRequest = queryToHttpRequest q
-  metadataRef <- newIORef mempty
-  resp <- attemptIO (id :: E.SomeException -> E.SomeException) $
-          runResourceT $ do
-            HTTP.Response status headers body <- HTTP.http httpRequest manager
-            responseConsumer request metadataRef status headers body
-  metadata <- readIORef metadataRef
-  return $ Response metadata resp
+  resp <- runResourceT $ do
+      HTTP.Response status headers body <- HTTP.http httpRequest manager
+      responseConsumer request metadataRef status headers body
+  return resp
 
 awsUri :: (SignQuery request
           , ConfigurationFetch (Info request))
diff --git a/Examples/GetObject.hs b/Examples/GetObject.hs
new file mode 100644
--- /dev/null
+++ b/Examples/GetObject.hs
@@ -0,0 +1,26 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+import qualified Aws
+import qualified Aws.S3 as S3
+import Data.Conduit
+import Data.Conduit.Binary
+import Data.IORef
+import Data.Monoid
+
+-- A small function to save the object's data into a file.
+saveObject :: Aws.HTTPResponseConsumer ()
+saveObject status headers source = source $$ sinkFile "cloud-remote.pdf"
+
+main :: IO ()
+main = do
+  -- Set up AWS credentials and the default configuration.
+  cfg <- Aws.baseConfiguration
+
+  -- Create an IORef to store the response Metadata (so it is also available in case of an error).
+  metadataRef <- newIORef mempty
+
+  -- Create a request object with S3.getObject and run the request with simpleAwsRef.
+  Aws.simpleAwsRef cfg metadataRef $ S3.getObject "haskell-aws" "cloud-remote.pdf" saveObject
+
+  -- Print the response metadata.
+  print =<< readIORef metadataRef
diff --git a/README b/README
deleted file mode 100644
--- a/README
+++ /dev/null
@@ -1,1 +0,0 @@
-Amazon Web Services for Haskell
diff --git a/README.org b/README.org
new file mode 100644
--- /dev/null
+++ b/README.org
@@ -0,0 +1,93 @@
+#+TITLE: Amazon Web Services for Haskell
+
+* Introduction
+
+The ~aws~ package attempts to provide support for using Amazon Web Services like S3 (storage), SQS (queuing) and others
+to Haskell programmers. The ultimate goal is to support all Amazon Web Services.
+
+* Installation
+
+Make sure you have a recent GHC installed, as well as cabal-install, and installation should be as easy as:
+
+#+BEGIN_SRC bash
+$ cabal install aws
+#+END_SRC
+
+If you prefer to install from source yourself, you should first get a clone of the ~aws~ repository, and install it from
+inside the source directory:
+
+#+BEGIN_SRC bash
+$ git clone https://github.com/aristidb/aws.git
+$ cd aws
+$ cabal install
+#+END_SRC
+
+* Using aws
+
+** Concepts and organisation
+
+The aws package is organised into the general =Aws= module namespace, and subnamespaces like =Aws.S3= for each Amazon Web
+Service. Under each service namespace in turn, there are general support modules and and =Aws.<Service>.Commands.<Command>=
+module for each command. For easier usage, there are the "bundling" modules =Aws= (general support), and =Aws.<Service>=.
+
+The primary concept in aws is the /Transaction/, which corresponds to a single HTTP request to the Amazon Web Services.
+A transaction consists of a request and a response, which are associated together via the =Transaction= typeclass. Requests
+and responses are simple Haskell records, but for some requests there are convenience functions to fill in default values
+for many parameters.
+
+** Example usage
+
+To be able to access AWS resources, you should put your into a configuration file. (You don't have to store it in a file,
+but that's how we do it in this example.) Save the following in ~$HOME/.aws-keys~.
+
+#+BEGIN_EXAMPLE
+default AccessKeyID SecretKey
+#+END_EXAMPLE
+
+You do have to replace AccessKeyID and SecretKey with the Access Key ID and the Secret Key respectively, of course.
+
+Then, copy this example into a Haskell file, and run it with ~runghc~:
+
+#+BEGIN_SRC haskell
+{-# LANGUAGE OverloadedStrings #-}
+
+import qualified Aws
+import qualified Aws.S3 as S3
+import Data.Conduit
+import Data.Conduit.Binary
+import Data.IORef
+import Data.Monoid
+
+{- A small function to save the object's data into a file. -}
+saveObject :: Aws.HTTPResponseConsumer ()
+saveObject status headers source = source $$ sinkFile "cloud-remote.pdf"
+
+main :: IO ()
+main = do
+  {- Set up AWS credentials and the default configuration. -}
+  cfg <- Aws.baseConfiguration
+
+  {- Create an IORef to store the response Metadata (so it is also available in case of an error). -}
+  metadataRef <- newIORef mempty
+
+  {- Create a request object with S3.getObject and run the request with simpleAwsRef. -}
+  Aws.simpleAwsRef cfg metadataRef $ S3.getObject "haskell-aws" "cloud-remote.pdf" saveObject
+
+  {- Print the response metadata. -}
+  print =<< readIORef metadataRef
+#+END_SRC
+
+You can also find this example in the source distribution in the ~Examples/~ folder.
+
+* Release Notes
+
+** 0.3 series
+
+- 0.3.2 :: Add awsRef / simpleAwsRef request variants for those who prefer an =IORef= over a =Data.Attempt.Attempt= value.
+           Also improve README and add simple example.
+
+* Resources
+
+- [[https://github.com/aristidb/aws][aws on Github]]
+- [[http://hackage.haskell.org/package/aws][aws on Hackage]] (includes reference documentation)
+- [[http://aws.amazon.com/][Official Amazon Web Services website]]
diff --git a/aws.cabal b/aws.cabal
--- a/aws.cabal
+++ b/aws.cabal
@@ -6,7 +6,7 @@
 -- The package version. See the Haskell package versioning policy
 -- (http://www.haskell.org/haskellwiki/Package_versioning_policy) for
 -- standards guiding when and how versions should be incremented.
-Version:             0.3.1
+Version:             0.3.2
 
 -- A short (one-line) description of the package.
 Synopsis:            Amazon Web Services (AWS) for Haskell
@@ -39,7 +39,8 @@
 
 -- Extra files to be distributed with the package, such as examples or
 -- a README.
-Extra-source-files:  README
+Extra-source-files:  README.org
+                     Examples/GetObject.hs
 
 -- Constraint on the version of Cabal needed to build this package.
 Cabal-version:       >=1.8
@@ -47,7 +48,7 @@
 Source-repository this
   type: git
   location: https://github.com/aristidb/aws.git
-  tag: 0.3.1
+  tag: 0.3.2
 
 Source-repository head
   type: git