diff --git a/interpolate.cabal b/interpolate.cabal
--- a/interpolate.cabal
+++ b/interpolate.cabal
@@ -1,5 +1,5 @@
 name:             interpolate
-version:          0.0.1
+version:          0.0.2
 license:          MIT
 license-file:     LICENSE
 copyright:        (c) 2013 Simon Hengel
@@ -51,3 +51,16 @@
     , hspec >= 1.5
     , QuickCheck
     , quickcheck-instances
+
+test-suite doctests
+  type:
+      exitcode-stdio-1.0
+  ghc-options:
+      -Wall -Werror
+  hs-source-dirs:
+      test
+  main-is:
+      doctests.hs
+  build-depends:
+      base    == 4.*
+    , doctest == 0.9.*
diff --git a/src/Data/String/Interpolate.hs b/src/Data/String/Interpolate.hs
--- a/src/Data/String/Interpolate.hs
+++ b/src/Data/String/Interpolate.hs
@@ -1,5 +1,14 @@
 {-# LANGUAGE TemplateHaskell #-}
-module Data.String.Interpolate (i) where
+module Data.String.Interpolate (
+-- * String interpolation done right
+-- |
+-- The examples in this module use `QuasiQuotes`.  Make sure to enable the
+-- corresponding language extension.
+--
+-- >>> :set -XQuasiQuotes
+-- >>> import Data.String.Interpolate
+  i
+) where
 
 import           Language.Haskell.TH.Quote (QuasiQuoter(..))
 import           Language.Haskell.Meta.Parse.Careful (parseExp)
@@ -8,6 +17,27 @@
 import           Data.String.Interpolate.Parse
 import           Data.String.Interpolate.Compat (Q, Exp, appE, reportError)
 
+-- |
+-- A `QuasiQuoter` for string interpolation.  Expression enclosed within
+-- @#{...}@ are interpolated, the result has to be in the `Show` class.
+--
+-- It interpolates strings
+--
+-- >>> let name = "Marvin"
+-- >>> putStrLn [i|name: #{name}|]
+-- name: Marvin
+--
+-- or integers
+--
+-- >>> let age = 23
+-- >>> putStrLn [i|age: #{age}|]
+-- age: 23
+--
+-- or arbitrary Haskell expressions
+--
+-- >>> let profession = "\955-scientist"
+-- >>> putStrLn [i|profession: #{unwords [name, "the", profession]}|]
+-- profession: Marvin the λ-scientist
 i :: QuasiQuoter
 i = QuasiQuoter {
     quoteExp = toExp . parseNodes
diff --git a/test/doctests.hs b/test/doctests.hs
new file mode 100644
--- /dev/null
+++ b/test/doctests.hs
@@ -0,0 +1,6 @@
+module Main where
+
+import           Test.DocTest
+
+main :: IO ()
+main = doctest ["-isrc", "-optP-include", "-optPdist/build/autogen/cabal_macros.h", "src/Data/String/Interpolate.hs"]