diff --git a/CHANGELOG.md b/CHANGELOG.md
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 0.5.2.1
+
+* Improved documentation
+
 ## 0.5.2.0
 
 * Added `Opaleye.FunctionalJoin`
diff --git a/opaleye.cabal b/opaleye.cabal
--- a/opaleye.cabal
+++ b/opaleye.cabal
@@ -1,6 +1,6 @@
 name:            opaleye
 copyright:       Copyright (c) 2014-2016 Purely Agile Limited
-version:         0.5.2.0
+version:         0.5.2.1
 synopsis:        An SQL-generating DSL targeting PostgreSQL
 description:     An SQL-generating DSL targeting PostgreSQL.  Allows
                  Postgres queries to be written within Haskell in a
diff --git a/src/Opaleye/Aggregate.hs b/src/Opaleye/Aggregate.hs
--- a/src/Opaleye/Aggregate.hs
+++ b/src/Opaleye/Aggregate.hs
@@ -1,8 +1,32 @@
 -- | Perform aggregation on 'Query's.  To aggregate a 'Query' you
 -- should construct an 'Aggregator' encoding how you want the
--- aggregation to proceed, then call 'aggregate' on it.
+-- aggregation to proceed, then call 'aggregate' on it.  The
+-- 'Aggregator' should be constructed from the basic 'Aggregator's
+-- below by using the combining operations from
+-- "Data.Profunctor.Product".
 
-module Opaleye.Aggregate (module Opaleye.Aggregate, Aggregator) where
+module Opaleye.Aggregate
+       (
+       -- * Aggregation
+         aggregate
+       , Aggregator
+       -- * Basic 'Aggregator's
+       , groupBy
+       , Opaleye.Aggregate.sum
+       , count
+       , countStar
+       , avg
+       , Opaleye.Aggregate.max
+       , Opaleye.Aggregate.min
+       , boolOr
+       , boolAnd
+       , arrayAgg
+       , stringAgg
+       -- * Counting rows
+       , countRows
+       -- * Entire module
+       , module Opaleye.Aggregate
+       ) where
 
 import           Control.Applicative (pure)
 import           Data.Profunctor     (lmap)
@@ -38,10 +62,10 @@
 Please note that when aggregating an empty query with no @GROUP BY@
 clause, Opaleye's behaviour differs from Postgres's behaviour.
 Postgres returns a single row whereas Opaleye returns zero rows.
-(Opaleye's behaviour is consistent with the meaning of aggregating
+Opaleye's behaviour is consistent with the meaning of aggregating
 over groups of rows and Postgres's behaviour is inconsistent.  When a
 query has zero rows it has zero groups, and thus zero rows in the
-result of an aggregation.)
+result of an aggregation.
 
 -}
 aggregate :: Aggregator a b -> Query a -> Query b
diff --git a/src/Opaleye/Binary.hs b/src/Opaleye/Binary.hs
--- a/src/Opaleye/Binary.hs
+++ b/src/Opaleye/Binary.hs
@@ -37,6 +37,8 @@
 
 import           Data.Profunctor.Product.Default (Default, def)
 
+-- * Binary operations
+
 unionAll :: Default B.Binaryspec columns columns =>
             Query columns -> Query columns -> Query columns
 unionAll = unionAllExplicit def
@@ -67,6 +69,7 @@
          Query columns -> Query columns -> Query columns
 except = exceptExplicit def
 
+-- * Explicit versions
 
 unionAllExplicit :: B.Binaryspec columns columns'
                  -> Query columns -> Query columns -> Query columns'
diff --git a/src/Opaleye/Column.hs b/src/Opaleye/Column.hs
--- a/src/Opaleye/Column.hs
+++ b/src/Opaleye/Column.hs
@@ -3,13 +3,23 @@
 -- Please note that numeric 'Column' types are instances of 'Num', so
 -- you can use '*', '/', '+', '-' on them.
 
-module Opaleye.Column (Column,
-                       module Opaleye.Column,
+module Opaleye.Column (-- * 'Column'
+                       Column,
+                       -- * Working with @NULL@
                        Nullable,
+                       null,
+                       isNull,
+                       matchNullable,
+                       fromNullable,
+                       toNullable,
+                       maybeToNullable,
+                       -- * Unsafe operations
                        unsafeCast,
                        unsafeCoerce,
                        unsafeCoerceColumn,
-                       unsafeCompositeField)  where
+                       unsafeCompositeField,
+                       -- * Entire module
+                       module Opaleye.Column)  where
 
 import           Opaleye.Internal.Column (Column, Nullable, unsafeCoerce, unsafeCoerceColumn,
                                           unsafeCast, unsafeCompositeField)
diff --git a/src/Opaleye/Internal/Aggregate.hs b/src/Opaleye/Internal/Aggregate.hs
--- a/src/Opaleye/Internal/Aggregate.hs
+++ b/src/Opaleye/Internal/Aggregate.hs
@@ -19,6 +19,9 @@
 them, and transforms each group into a single row of type @b@. This
 corresponds to aggregators using @GROUP BY@ in SQL.
 
+You should combine basic 'Aggregator's into 'Aggregator's on compound
+types by using the operations in "Data.Profunctor.Product".
+
 An 'Aggregator' corresponds closely to a 'Control.Foldl.Fold' from the
 @foldl@ package.  Whereas an 'Aggregator' @a@ @b@ takes each group of
 type @a@ to a single row of type @b@, a 'Control.Foldl.Fold' @a@ @b@
diff --git a/src/Opaleye/Internal/Column.hs b/src/Opaleye/Internal/Column.hs
--- a/src/Opaleye/Internal/Column.hs
+++ b/src/Opaleye/Internal/Column.hs
@@ -17,7 +17,7 @@
 unColumn :: Column a -> HPQ.PrimExpr
 unColumn (Column e) = e
 
-{-# DEPRECATED unsafeCoerce "Use unsafeCoerceColumn instead" #-}
+{-# DEPRECATED unsafeCoerce "Will be deprecated in version 0.6.  Use unsafeCoerceColumn instead." #-}
 unsafeCoerce :: Column a -> Column b
 unsafeCoerce = unsafeCoerceColumn
 
diff --git a/src/Opaleye/Internal/Order.hs b/src/Opaleye/Internal/Order.hs
--- a/src/Opaleye/Internal/Order.hs
+++ b/src/Opaleye/Internal/Order.hs
@@ -14,10 +14,11 @@
 import qualified Data.Void as Void
 
 {-|
-An `Order` represents an expression to order on and a sort
-direction. Multiple `Order`s can be composed with
+An `Order` @a@ represents a sort order and direction for the elements
+of the type @a@. Multiple `Order`s can be composed with
 `Data.Monoid.mappend` or @(\<\>)@ from "Data.Monoid".  If two rows are
-equal according to the first `Order`, the second is used, and so on.
+equal according to the first `Order` in the @mappend@, the second is
+used, and so on.
 -}
 
 -- Like the (columns -> RowParser haskells) field of QueryRunner this
diff --git a/src/Opaleye/Join.hs b/src/Opaleye/Join.hs
--- a/src/Opaleye/Join.hs
+++ b/src/Opaleye/Join.hs
@@ -34,6 +34,8 @@
 
 import qualified Data.Profunctor.Product.Default as D
 
+-- * Joins
+
 leftJoin  :: (D.Default U.Unpackspec columnsL columnsL,
               D.Default U.Unpackspec columnsR columnsR,
               D.Default J.NullMaker columnsR nullableColumnsR)
@@ -62,6 +64,8 @@
           -> ((columnsL, columnsR) -> Column T.PGBool) -- ^ Condition on which to join
           -> Query (nullableColumnsL, nullableColumnsR) -- ^ Full outer join
 fullJoin = fullJoinExplicit D.def D.def D.def D.def
+
+-- * Explicit versions
 
 leftJoinExplicit :: U.Unpackspec columnsL columnsL
                  -> U.Unpackspec columnsR columnsR
diff --git a/src/Opaleye/Manipulation.hs b/src/Opaleye/Manipulation.hs
--- a/src/Opaleye/Manipulation.hs
+++ b/src/Opaleye/Manipulation.hs
@@ -19,6 +19,7 @@
 -- @
 
 module Opaleye.Manipulation (module Opaleye.Manipulation,
+                             -- * Other
                              U.Unpackspec) where
 
 import qualified Opaleye.Internal.Sql as Sql
@@ -46,6 +47,8 @@
 import           Data.String (fromString)
 import qualified Data.List.NonEmpty as NEL
 
+-- * Manipulation functions
+
 -- | Insert rows into a table
 runInsertMany :: PGS.Connection
               -- ^
@@ -131,6 +134,8 @@
           -- ^ The number of rows deleted
 runDelete conn = PGS.execute_ conn . fromString .: arrangeDeleteSql
 
+-- * Explicit versions
+
 -- | You probably don't need this, but can just use
 -- 'runInsertReturning' instead.  You only need it if you want to run
 -- an INSERT RETURNING statement but need to be explicit about the
@@ -184,9 +189,12 @@
         parser = IRQ.prepareRowParser qr (r v)
         TI.Table _ (TI.TableProperties _ (TI.View v)) = t
 
+-- * Deprecated versions
+
 -- | Returns the number of rows inserted
 --
--- This will be deprecated in a future release.  Use 'runInsertMany' instead.
+-- This will be deprecated in version 0.6.  Use 'runInsertMany'
+-- instead.
 runInsert :: PGS.Connection -> T.Table columns columns' -> columns -> IO Int64
 runInsert conn = PGS.execute_ conn . fromString .: arrangeInsertSql
 
@@ -195,7 +203,7 @@
 -- recommended that you provide full type signatures when using
 -- @runInsertReturning@.
 --
--- This will be deprecated in a future release.  Use
+-- This will be deprecated in version 0.6.  Use
 -- 'runInsertManyReturning' instead.
 runInsertReturning :: (D.Default RQ.QueryRunner columnsReturned haskells)
                    => PGS.Connection
@@ -205,18 +213,18 @@
                    -> IO [haskells]
 runInsertReturning = runInsertReturningExplicit D.def
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeInsert :: T.Table columns a -> columns -> HSql.SqlInsert
 arrangeInsert t c = arrangeInsertMany t (return c)
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeInsertSql :: T.Table columns a -> columns -> String
 arrangeInsertSql = show . HPrint.ppInsert .: arrangeInsert
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeInsertMany :: T.Table columns a -> NEL.NonEmpty columns -> HSql.SqlInsert
 arrangeInsertMany table columns = insert
   where writer = TI.tablePropertiesWriter (TI.tableProperties table)
@@ -225,13 +233,13 @@
                       (PQ.tiToSqlTable (TI.tableIdentifier table))
                       columnNames columnExprs
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeInsertManySql :: T.Table columns a -> NEL.NonEmpty columns -> String
 arrangeInsertManySql = show . HPrint.ppInsert .: arrangeInsertMany
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeUpdate :: T.Table columnsW columnsR
               -> (columnsR -> columnsW) -> (columnsR -> Column PGBool)
               -> HSql.SqlUpdate
@@ -243,28 +251,28 @@
         update' = map (\(x, y) -> (y, x)) . TI.runWriter writer . update
         Column condExpr = cond tableCols
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeUpdateSql :: T.Table columnsW columnsR
               -> (columnsR -> columnsW) -> (columnsR -> Column PGBool)
               -> String
 arrangeUpdateSql = show . HPrint.ppUpdate .:. arrangeUpdate
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeDelete :: T.Table a columnsR -> (columnsR -> Column PGBool) -> HSql.SqlDelete
 arrangeDelete table cond =
   SG.sqlDelete SD.defaultSqlGenerator (PQ.tiToSqlTable (TI.tableIdentifier table)) [condExpr]
   where Column condExpr = cond tableCols
         TI.View tableCols = TI.tablePropertiesView (TI.tableProperties table)
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeDeleteSql :: T.Table a columnsR -> (columnsR -> Column PGBool) -> String
 arrangeDeleteSql = show . HPrint.ppDelete .: arrangeDelete
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeInsertManyReturning :: U.Unpackspec columnsReturned ignored
                            -> T.Table columnsW columnsR
                            -> NEL.NonEmpty columnsW
@@ -277,8 +285,8 @@
         returningPEs = U.collectPEs unpackspec (returningf columnsR)
         returningSEs = Sql.ensureColumnsGen id (map Sql.sqlExpr returningPEs)
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeInsertManyReturningSql :: U.Unpackspec columnsReturned ignored
                               -> T.Table columnsW columnsR
                               -> NEL.NonEmpty columnsW
@@ -287,8 +295,8 @@
 arrangeInsertManyReturningSql =
   show . Print.ppInsertReturning .:: arrangeInsertManyReturning
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeUpdateReturning :: U.Unpackspec columnsReturned ignored
                        -> T.Table columnsW columnsR
                        -> (columnsR -> columnsW)
@@ -302,8 +310,8 @@
         returningPEs = U.collectPEs unpackspec (returningf columnsR)
         returningSEs = Sql.ensureColumnsGen id (map Sql.sqlExpr returningPEs)
 
--- | For internal use only.  Do not use.  Will be removed in a
--- subsequent release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 arrangeUpdateReturningSql :: U.Unpackspec columnsReturned ignored
                           -> T.Table columnsW columnsR
                           -> (columnsR -> columnsW)
diff --git a/src/Opaleye/Operators.hs b/src/Opaleye/Operators.hs
--- a/src/Opaleye/Operators.hs
+++ b/src/Opaleye/Operators.hs
@@ -4,8 +4,7 @@
 -- | Operators on 'Column's.  Please note that numeric 'Column' types
 -- are instances of 'Num', so you can use '*', '/', '+', '-' on them.
 
-module Opaleye.Operators (module Opaleye.Operators,
-                          (O..&&)) where
+module Opaleye.Operators (module Opaleye.Operators) where
 
 import qualified Control.Arrow as A
 import qualified Data.Foldable as F
@@ -29,6 +28,8 @@
 
 import qualified Data.Profunctor.Product.Default as D
 
+-- * Restriction operators
+
 {-| Restrict query results to a particular condition.  Corresponds to
 the guard method of the MonadPlus class.  You would typically use
 'restrict' if you want to use 'A.Arrow' notation.  -}
@@ -45,6 +46,8 @@
   restrict  -< p a
   A.returnA -< a
 
+-- * Equality operators
+
 infix 4 .==
 (.==) :: Column a -> Column a -> Column T.PGBool
 (.==) = C.binOp (HPQ.:==)
@@ -63,10 +66,12 @@
 infix 4 ./==
 -- | A polymorphic inequality operator that works for all types that
 -- you have run `makeAdaptorAndInstance` on.  This may be unified with
--- `.==` in a future version.
+-- `./=` in a future version.
 (./==) :: D.Default O.EqPP columns columns => columns -> columns -> Column T.PGBool
 (./==) = Opaleye.Operators.not .: (O..==)
 
+-- * Comparison operators
+
 infix 4 .>
 (.>) :: Ord.PGOrd a => Column a -> Column a -> Column T.PGBool
 (.>) = unsafeGt
@@ -83,12 +88,16 @@
 (.>=) :: Ord.PGOrd a => Column a -> Column a -> Column T.PGBool
 (.>=) = C.binOp (HPQ.:>=)
 
+-- * Numerical operators
+
 quot_ :: C.PGIntegral a => Column a -> Column a -> Column a
 quot_ = C.binOp (HPQ.:/)
 
 rem_ :: C.PGIntegral a => Column a -> Column a -> Column a
 rem_ = C.binOp HPQ.OpMod
 
+-- * Conditional operators
+
 case_ :: [(Column T.PGBool, Column a)] -> Column a -> Column a
 case_ = unsafeCase_
 
@@ -106,15 +115,28 @@
                -> columns
 ifThenElseMany = O.ifExplict D.def
 
+-- * Logical operators
+
 infixr 2 .||
 
 -- | Boolean or
 (.||) :: Column T.PGBool -> Column T.PGBool -> Column T.PGBool
 (.||) = C.binOp HPQ.OpOr
 
+-- | Boolean and
+(.&&) :: Column T.PGBool -> Column T.PGBool -> Column T.PGBool
+(.&&) = (O..&&)
+
+-- | Boolean not
 not :: Column T.PGBool -> Column T.PGBool
 not = C.unOp HPQ.OpNot
 
+-- | True when any element of the container is true
+ors :: F.Foldable f => f (Column T.PGBool) -> Column T.PGBool
+ors = F.foldl' (.||) (T.pgBool False)
+
+-- * Text operators
+
 -- | Concatenate 'Column' 'T.PGText'
 (.++) :: Column T.PGText -> Column T.PGText -> Column T.PGText
 (.++) = C.binOp (HPQ.:||)
@@ -138,9 +160,7 @@
 charLength :: C.PGString a => Column a -> Column Int
 charLength (Column e) = Column (HPQ.FunExpr "char_length" [e])
 
--- | True when any element of the container is true
-ors :: F.Foldable f => f (Column T.PGBool) -> Column T.PGBool
-ors = F.foldl' (.||) (T.pgBool False)
+-- * Containment operators
 
 -- | 'in_' is designed to be used in prefix form.
 --
@@ -182,19 +202,7 @@
                      . snd)
               A.<<< qj
 
-timestamptzAtTimeZone :: Column T.PGTimestamptz
-                      -> Column T.PGText
-                      -> Column T.PGTimestamp
-timestamptzAtTimeZone = C.binOp HPQ.OpAtTimeZone
-
-emptyArray :: T.IsSqlType a => Column (T.PGArray a)
-emptyArray = T.pgArray id []
-
-arrayPrepend :: Column a -> Column (T.PGArray a) -> Column (T.PGArray a)
-arrayPrepend (Column e) (Column es) = Column (HPQ.FunExpr "array_prepend" [e, es])
-
-singletonArray :: T.IsSqlType a => Column a -> Column (T.PGArray a)
-singletonArray x = arrayPrepend x emptyArray
+-- * JSON operators
 
 -- | Class of Postgres types that represent json values.
 --
@@ -271,6 +279,22 @@
 infix 4 .?&
 (.?&) :: Column T.PGJsonb -> Column (T.PGArray T.PGText) -> Column T.PGBool
 (.?&) = C.binOp (HPQ.:?&)
+
+-- * Other operators
+
+timestamptzAtTimeZone :: Column T.PGTimestamptz
+                      -> Column T.PGText
+                      -> Column T.PGTimestamp
+timestamptzAtTimeZone = C.binOp HPQ.OpAtTimeZone
+
+emptyArray :: T.IsSqlType a => Column (T.PGArray a)
+emptyArray = T.pgArray id []
+
+arrayPrepend :: Column a -> Column (T.PGArray a) -> Column (T.PGArray a)
+arrayPrepend (Column e) (Column es) = Column (HPQ.FunExpr "array_prepend" [e, es])
+
+singletonArray :: T.IsSqlType a => Column a -> Column (T.PGArray a)
+singletonArray x = arrayPrepend x emptyArray
 
 -- | Cast a 'PGInt4' to a 'PGFloat8'
 doubleOfInt :: Column T.PGInt4 -> Column T.PGFloat8
diff --git a/src/Opaleye/Order.hs b/src/Opaleye/Order.hs
--- a/src/Opaleye/Order.hs
+++ b/src/Opaleye/Order.hs
@@ -1,6 +1,19 @@
 -- | Ordering, @LIMIT@ and @OFFSET@
 
-module Opaleye.Order (module Opaleye.Order, O.Order) where
+module Opaleye.Order ( -- * Order by
+                       orderBy
+                     , O.Order
+                     -- * Order direction
+                     , asc
+                     , desc
+                     , ascNullsFirst
+                     , descNullsLast
+                     -- * Limit and offset
+                     , limit
+                     , offset
+                     -- * Other
+                     , PGOrd
+                     ) where
 
 import qualified Opaleye.Column as C
 import           Opaleye.QueryArr (Query)
@@ -52,6 +65,8 @@
 descNullsLast = O.order HPQ.OrderOp { HPQ.orderDirection = HPQ.OpDesc
                                     , HPQ.orderNulls     = HPQ.NullsLast }
 
+-- * Limit and offset
+
 {- |
 Limit the results of the given query to the given maximum number of
 items.
@@ -65,6 +80,8 @@
 -}
 offset :: Int -> Query a -> Query a
 offset n a = Q.simpleQueryArr (O.offset' n . Q.runSimpleQueryArr a)
+
+-- * Other
 
 -- | Typeclass for Postgres types which support ordering operations.
 class PGOrd a where
diff --git a/src/Opaleye/PGTypes.hs b/src/Opaleye/PGTypes.hs
--- a/src/Opaleye/PGTypes.hs
+++ b/src/Opaleye/PGTypes.hs
@@ -46,6 +46,8 @@
 instance C.PGString PGCitext where
   pgFromString = pgCiLazyText . CI.mk . LText.pack
 
+-- * Creating SQL values
+
 pgString :: String -> Column PGText
 pgString = IPT.literalColumn . HPQ.StringLit
 
@@ -179,6 +181,8 @@
 instance IsSqlType PGJsonb where
   showPGType _ = "jsonb"
 
+-- * SQL datatypes
+
 data PGBool
 data PGDate
 data PGFloat4
@@ -198,14 +202,16 @@
 data PGJson
 data PGJsonb
 
+-- * Deprecated functions
+
 literalColumn :: HPQ.Literal -> Column a
 literalColumn = IPT.literalColumn
 {-# WARNING literalColumn
-    "'literalColumn' has been moved to Opaleye.Internal.PGTypes and will be deprecated in a future release"
+    "'literalColumn' has been moved to Opaleye.Internal.PGTypes and will be deprecated in version 0.6"
   #-}
 
 unsafePgFormatTime :: Time.FormatTime t => HPQ.Name -> String -> t -> Column c
 unsafePgFormatTime = IPT.unsafePgFormatTime
 {-# WARNING unsafePgFormatTime
-    "'unsafePgFormatTime' has been moved to Opaleye.Internal.PGTypes and will be deprecated in a future release"
+    "'unsafePgFormatTime' has been moved to Opaleye.Internal.PGTypes and will be deprecated in version 0.6"
   #-}
diff --git a/src/Opaleye/RunQuery.hs b/src/Opaleye/RunQuery.hs
--- a/src/Opaleye/RunQuery.hs
+++ b/src/Opaleye/RunQuery.hs
@@ -2,8 +2,10 @@
 
 module Opaleye.RunQuery (module Opaleye.RunQuery,
                          QueryRunner,
+                         -- * Datatypes
                          IRQ.QueryRunnerColumn,
                          IRQ.QueryRunnerColumnDefault (..),
+                         -- * Creating now 'QueryRunnerColumn's
                          IRQ.fieldQueryRunnerColumn,
                          IRQ.fieldParserQueryRunnerColumn) where
 
@@ -21,6 +23,8 @@
 import qualified Data.Profunctor as P
 import qualified Data.Profunctor.Product.Default as D
 
+-- * Running 'Query's
+
 -- | @runQuery@'s use of the 'D.Default' typeclass means that the
 -- compiler will have trouble inferring types.  It is strongly
 -- recommended that you provide full type signatures when using
@@ -61,6 +65,8 @@
   -> IO b
 runQueryFold = runQueryFoldExplicit D.def
 
+-- * Creating new 'QueryRunnerColumn's
+
 -- | Use 'queryRunnerColumn' to make an instance to allow you to run queries on
 --   your own datatypes.  For example:
 --
@@ -81,6 +87,8 @@
   where IRQ.QueryRunnerColumn u fp = qrc
         fmapFP = fmap . fmap . fmap
 
+-- * Explicit versions
+
 runQueryExplicit :: QueryRunner columns haskells
                  -> PGS.Connection
                  -> Query columns
@@ -100,8 +108,10 @@
   Just sql' -> PGS.foldWith_ parser conn sql' z f
   where (sql, parser) = prepareQuery qr q
 
--- | For internal use only.  Do not use.  Will be deprecated in a
--- subsequent release.
+-- * Deprecated functions
+
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 prepareQuery :: QueryRunner columns haskells -> Query columns -> (Maybe PGS.Query, FR.RowParser haskells)
 prepareQuery qr@(QueryRunner u _ _) q = (sql, parser)
   where sql :: Maybe PGS.Query
diff --git a/src/Opaleye/Sql.hs b/src/Opaleye/Sql.hs
--- a/src/Opaleye/Sql.hs
+++ b/src/Opaleye/Sql.hs
@@ -15,37 +15,70 @@
 
 import qualified Data.Profunctor.Product.Default as D
 
--- | When 'Nothing' is returned it means that the 'Query' returns zero rows.
+-- * Showing SQL
+
+-- | Show the SQL query string generated from the query.
 --
+-- When 'Nothing' is returned it means that the 'Query' returns zero
+-- rows.
+--
 -- Example type specialization:
 --
 -- @
--- showSqlForPostgres :: Query (Column a, Column b) -> Maybe String
+-- showSql :: Query (Column a, Column b) -> Maybe String
 -- @
 --
 -- Assuming the @makeAdaptorAndInstance@ splice has been run for the
 -- product type @Foo@:
 --
 -- @
--- showSqlForPostgres :: Query (Foo (Column a) (Column b) (Column c)) -> Maybe String
+-- showSql :: Query (Foo (Column a) (Column b) (Column c)) -> Maybe String
 -- @
+showSql :: forall columns.
+           D.Default U.Unpackspec columns columns
+        => Q.Query columns
+        -> Maybe String
+showSql = showSqlExplicit (D.def :: U.Unpackspec columns columns)
+
+-- | Show the unoptimized SQL query string generated from the query.
+showSqlUnopt :: forall columns.
+                D.Default U.Unpackspec columns columns
+             => Q.Query columns
+             -> Maybe String
+showSqlUnopt = showSqlUnoptExplicit (D.def :: U.Unpackspec columns columns)
+
+-- * Explicit versions
+
+showSqlExplicit :: U.Unpackspec columns b -> Q.Query columns -> Maybe String
+showSqlExplicit = formatAndShowSQL
+                  . (\(x, y, z) -> (x, Op.optimize y, z))
+                  .: Q.runQueryArrUnpack
+
+showSqlUnoptExplicit :: U.Unpackspec columns b -> Q.Query columns -> Maybe String
+showSqlUnoptExplicit = formatAndShowSQL .: Q.runQueryArrUnpack
+
+-- * Deprecated functions
+
+-- | Will be deprecated in version 0.7.  Use 'showSql' instead.
 showSqlForPostgres :: forall columns . D.Default U.Unpackspec columns columns =>
                       Q.Query columns -> Maybe String
-showSqlForPostgres = showSqlForPostgresExplicit (D.def :: U.Unpackspec columns columns)
+showSqlForPostgres = showSql
 
+-- | Will be deprecated in version 0.7.  Use 'showSqlUnopt' instead.
 showSqlForPostgresUnopt :: forall columns . D.Default U.Unpackspec columns columns =>
                            Q.Query columns -> Maybe String
-showSqlForPostgresUnopt = showSqlForPostgresUnoptExplicit (D.def :: U.Unpackspec columns columns)
+showSqlForPostgresUnopt = showSqlUnopt
 
+-- | Will be deprecated in version 0.7.  Use 'showSqlExplicit' instead.
 showSqlForPostgresExplicit :: U.Unpackspec columns b -> Q.Query columns -> Maybe String
-showSqlForPostgresExplicit = formatAndShowSQL
-                             . (\(x, y, z) -> (x, Op.optimize y, z))
-                             .: Q.runQueryArrUnpack
+showSqlForPostgresExplicit = showSqlExplicit
 
+-- | Will be deprecated in version 0.7.  Use 'showSqlUnoptExplicit' instead.
 showSqlForPostgresUnoptExplicit :: U.Unpackspec columns b -> Q.Query columns -> Maybe String
-showSqlForPostgresUnoptExplicit = formatAndShowSQL .: Q.runQueryArrUnpack
+showSqlForPostgresUnoptExplicit = showSqlUnoptExplicit
 
--- | For internal use only.  Do not use.  Will be deprecated in a future release.
+-- | For internal use only.  Do not use.  Will be deprecated in
+-- version 0.6.
 formatAndShowSQL :: ([HPQ.PrimExpr], PQ.PrimQuery' a, T.Tag) -> Maybe String
 formatAndShowSQL = fmap (show . Pr.ppSql . Sql.sql) . traverse2Of3 Op.removeEmpty
   where -- Just a lens
diff --git a/src/Opaleye/Table.hs b/src/Opaleye/Table.hs
--- a/src/Opaleye/Table.hs
+++ b/src/Opaleye/Table.hs
@@ -1,6 +1,7 @@
 {-# LANGUAGE FlexibleContexts #-}
 
 module Opaleye.Table (module Opaleye.Table,
+                      -- * Other
                       View,
                       Writer,
                       Table(Table, TableWithSchema),
@@ -34,12 +35,6 @@
               Table a columns -> Q.Query columns
 queryTable = queryTableExplicit D.def
 
-queryTableExplicit :: TM.ColumnMaker tablecolumns columns ->
-                     Table a tablecolumns -> Q.Query columns
-queryTableExplicit cm table = Q.simpleQueryArr f where
-  f ((), t0) = (retwires, primQ, Tag.next t0) where
-    (retwires, primQ) = T.queryTable cm table t0
-
 -- | 'required' is for columns which are not 'optional'.  You must
 -- provide them on writes.
 required :: String -> TableProperties (Column a) (Column a)
@@ -53,3 +48,11 @@
 optional columnName = T.TableProperties
   (T.optional columnName)
   (View (Column (HPQ.BaseTableAttrExpr columnName)))
+
+-- * Explicit versions
+
+queryTableExplicit :: TM.ColumnMaker tablecolumns columns ->
+                     Table a tablecolumns -> Q.Query columns
+queryTableExplicit cm table = Q.simpleQueryArr f where
+  f ((), t0) = (retwires, primQ, Tag.next t0) where
+    (retwires, primQ) = T.queryTable cm table t0