diff --git a/CHANGELOG.md b/CHANGELOG.md
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,8 @@
 Changelog for tmp-postgres
 
+1.23.0.2
+  #183 More Doc
+
 1.23.0.1
   #182 Doc Fixies
 
diff --git a/src/Database/Postgres/Temp.hs b/src/Database/Postgres/Temp.hs
--- a/src/Database/Postgres/Temp.hs
+++ b/src/Database/Postgres/Temp.hs
@@ -80,6 +80,7 @@
   , stopPostgres
   , stopPostgresGracefully
   -- * Making Starting Faster
+  -- $makingItFaster
   -- ** @initdb@ Data Directory Caching
   -- *** Exception safe interface
   , withDbCache
@@ -128,3 +129,32 @@
 import Database.Postgres.Temp.Internal
 import Database.Postgres.Temp.Internal.Core
 import Database.Postgres.Temp.Internal.Config
+
+{- $makingItFaster
+
+'with' and related functions are fast by themselves but
+by utilizing various forms of caching we can make them
+much faster.
+
+The slowest part of starting a new @postgres@ cluster is the @initdb@
+call which initializes the database files. However for a given @initdb@ version and configuration parameters the output
+is the same.
+
+To take advantage of this idempotent behavior we can cache the output of
+@initdb@ and copy the outputted database cluster files instead of recreating
+them. This leads to a 4x improvement in startup time.
+
+See `withDbCache` and related functions for more details.
+
+Additionally one can take snapshots of a database cluster and start
+new @postgres@ instances using the snapshot as an initial database
+cluster.
+
+This is useful if one has tests that require a time consuming migration
+process. By taking a snapshot after the migration we can start new
+isolated clusters from the point in time after the migration but before any
+test data has tainted the database.
+
+See 'withSnapshot' for details.
+
+-}
diff --git a/src/Database/Postgres/Temp/Internal.hs b/src/Database/Postgres/Temp/Internal.hs
--- a/src/Database/Postgres/Temp/Internal.hs
+++ b/src/Database/Postgres/Temp/Internal.hs
@@ -541,6 +541,14 @@
 Equivalent to 'withDbCacheConfig' with the 'CacheConfig'
 'defaultCacheConfig' makes.
 
+Here is an example using caching:
+
+@
+ withDbCache $ \\cache -> do
+  withCache (cacheResourcesToConfig cache) $ \\db -> ...
+  withCache (cacheResourcesToConfig cache) $ \\db -> ...
+@
+
 @since 1.20.0.0
 -}
 withDbCache :: (CacheResources -> IO a) -> IO a
@@ -615,6 +623,17 @@
 
 Snapshots are useful if you would like to start every test from a migrated database
 and the migration process is more time consuming then copying the additional data.
+
+Here is an example with caching and snapshots:
+
+@
+ withDbCache $ \\cache -> withConfig (cacheResourcesToConfig cache) $ \\db ->
+  migrate db
+  withSnapshot Temporary db $ \\snapshot -> do
+    withConfig (snapshotConfig db) $ \\migratedDb -> ...
+    withConfig (snapshotConfig db) $ \\migratedDb -> ...
+    withConfig (snapshotConfig db) $ \\migratedDb -> ...
+@
 
 @since 1.20.0.0
 -}
diff --git a/tmp-postgres.cabal b/tmp-postgres.cabal
--- a/tmp-postgres.cabal
+++ b/tmp-postgres.cabal
@@ -1,5 +1,5 @@
 name:                tmp-postgres
-version:             1.23.0.1
+version:             1.23.0.2
 synopsis: Start and stop a temporary postgres
 description: Start and stop a temporary postgres. See README.md
 homepage:            https://github.com/jfischoff/tmp-postgres#readme