diff --git a/Changelog.md b/Changelog.md
--- a/Changelog.md
+++ b/Changelog.md
@@ -1,6 +1,10 @@
 # Change log for esqueleto text search 
 
 
+## Version 1.1.4
++ link to new homepage
++ add better documentation. rexport important stuff in the main module explicetly
+
 ## Version 1.1.3
 + update maintainer field to me.
 + update copyright field.
diff --git a/esqueleto-textsearch.cabal b/esqueleto-textsearch.cabal
--- a/esqueleto-textsearch.cabal
+++ b/esqueleto-textsearch.cabal
@@ -1,8 +1,8 @@
 name:               esqueleto-textsearch
-version:            1.1.3
+version:            1.1.4
 synopsis:           PostgreSQL full text search for Esqueleto
 description:        PostgreSQL text search functions for Esqueleto.
-homepage:           https://github.com/SupercedeTech/esqueleto-textsearch-ii
+homepage:           https://github.com/jappeace/esqueleto-textsearch
 license:            MIT
 license-file:       LICENSE
 author:             Jappie Klooster <hi@jappie.me>, Alberto Valverde González
diff --git a/src/Database/Esqueleto/TextSearch.hs b/src/Database/Esqueleto/TextSearch.hs
--- a/src/Database/Esqueleto/TextSearch.hs
+++ b/src/Database/Esqueleto/TextSearch.hs
@@ -1,8 +1,19 @@
-
+{-# OPTIONS_GHC -Wno-duplicate-exports #-}
 -- | Haskell bindings for postgres full text search.
---   for a good explenation see https://rachbelaid.com/postgres-full-text-search-is-good-enough/
+--   for a good explenation see <https://rachbelaid.com/postgres-full-text-search-is-good-enough/>
+--
+--   see the [readme](https://hackage.haskell.org/package/esqueleto-textsearch#tutorial) for a full tutorial.
 module Database.Esqueleto.TextSearch (
-    module Database.Esqueleto.TextSearch.Language
+   (@@.)
+  , prefixAndQuery
+  , toSearchTerm
+  , SearchTerm
+  , ts_rank
+  , defaultWeights
+  , Weights (..)
+  , RegConfig
+  , NormalizationOption(..)
+  , module Database.Esqueleto.TextSearch.Language
   , module Database.Esqueleto.TextSearch.Types
 ) where
 
diff --git a/src/Database/Esqueleto/TextSearch/Language.hs b/src/Database/Esqueleto/TextSearch/Language.hs
--- a/src/Database/Esqueleto/TextSearch/Language.hs
+++ b/src/Database/Esqueleto/TextSearch/Language.hs
@@ -27,9 +27,21 @@
 import qualified Data.Text as T
 import Data.List.NonEmpty(nonEmpty, NonEmpty, toList)
 
+
+-- | Apply some query to a tsvector document
+--   for example:
+--
+-- @
+-- searchCompany :: SqlExpr (Entity CompanySearchIndex) -> SearchTerm -> SqlQuery ()
+-- searchCompany company term = do
+--   let query = prefixAndQuery term
+--       norm = val []
+--   where_ $ (company ^. CompanySearchIndexDocument) @@. query
+-- @
+--
 (@@.)
-  :: SqlExpr (Value TsVector)
-  -> SqlExpr (Value (TsQuery Lexemes))
+  :: SqlExpr (Value TsVector) -- ^ the document to search in
+  -> SqlExpr (Value (TsQuery Lexemes)) -- ^ the query made by 'prefixAndQuery'
   -> SqlExpr (Value Bool)
 (@@.) = unsafeSqlBinOp "@@"
 
@@ -52,11 +64,26 @@
   -> SqlExpr (Value (TsQuery Lexemes))
 plainto_tsquery a b = unsafeSqlFunction "plainto_tsquery" (a, b)
 
+-- | Organize search result by weights. This allows you to put better
+--   matching results higher.
+--   for example:
+--
+-- @
+-- searchCompany :: SqlExpr (Entity CompanySearchIndex) -> SearchTerm -> SqlQuery ()
+-- searchCompany company term = do
+--   let query = prefixAndQuery term
+--       norm = val []
+--   where_ $ (company ^. CompanySearchIndexDocument) @@. query
+--   orderBy [desc (ts_rank (val defaultWeights)
+--                  (company ^. CompanySearchIndexDocument)
+--                  query norm)]
+-- @
+--
 ts_rank
-  :: SqlExpr (Value Weights)
-  -> SqlExpr (Value TsVector)
-  -> SqlExpr (Value (TsQuery Lexemes))
-  -> SqlExpr (Value [NormalizationOption])
+  :: SqlExpr (Value Weights) -- ^ relative weighting of a b c and d, see 'defaultWeights'
+  -> SqlExpr (Value TsVector) -- ^ the document to search in
+  -> SqlExpr (Value (TsQuery Lexemes)) -- ^ the query made by 'prefixAndQuery'
+  -> SqlExpr (Value [NormalizationOption]) -- ^ normalization option to indicate how to deal with document length
   -> SqlExpr (Value Double)
 ts_rank a b c d = unsafeSqlFunction "ts_rank" (a, b, c, d)
 
@@ -85,9 +112,13 @@
 -- | format the query into lexemes
 --   the result can be used in '@@.' for example:
 --
---   @
---      where_ $ (index ^. UnitSearchIndexDocument) @@. prefixAndQuery query
---   @
+-- @
+-- searchCompany :: SqlExpr (Entity CompanySearchIndex) -> SearchTerm -> SqlQuery ()
+-- searchCompany company term = do
+--   let query = prefixAndQuery term
+--       norm = val []
+--   where_ $ (company ^. CompanySearchIndexDocument) @@. query
+-- @
 --
 prefixAndQuery :: SearchTerm -> SqlExpr (Value (TsQuery Lexemes))
 prefixAndQuery = prefixAndQueryLang "english"
@@ -99,12 +130,17 @@
   $ map (to_tsquery (val language) . val . Word Prefix []) $ toList ts
 
 
--- | A valid search term
+-- | A valid search term.
+--   created with 'toSearchTerm'.
 newtype SearchTerm = SearchTerm { unQuery :: NonEmpty Text }
   deriving (Show)
 
--- | constructs a valid search query, removes a bunch of illegal
---   characters and splits the terms for better results
+-- | Constructs a valid search query, removes a bunch of illegal
+--   characters and splits the terms for better results.
+--   Also checks if there is anything in the search term.
+--
+--   using a search term is optional, but it's probably what you want.
+--   all underlying primitives are exposed.
 toSearchTerm :: Text -> Maybe SearchTerm
 toSearchTerm q = SearchTerm <$> nonEmpty qs
   -- We disallow whitespace, \ and ' for the sake of producing a Text
diff --git a/src/Database/Esqueleto/TextSearch/Types.hs b/src/Database/Esqueleto/TextSearch/Types.hs
--- a/src/Database/Esqueleto/TextSearch/Types.hs
+++ b/src/Database/Esqueleto/TextSearch/Types.hs
@@ -41,14 +41,18 @@
 import Database.Persist
 import Database.Persist.Postgresql
 
+-- | ranking functions take an integer normalization option that specifies
+--   whether and how a document's length should impact its rank.
+--  The integer option controls several behaviors, so it is a bit mask: you can specify one or more behaviors using | (for example, 2|4).
+--  https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING
 data NormalizationOption
-  = NormNone
-  | Norm1LogLength
-  | NormLength
-  | NormMeanHarmDist
-  | NormUniqueWords
-  | Norm1LogUniqueWords
-  | Norm1Self
+  = NormNone -- ^ 0 (the default) ignores the document length
+  | Norm1LogLength -- ^ 1 divides the rank by 1 + the logarithm of the document length
+  | NormLength -- ^ 2 divides the rank by the document length
+  | NormMeanHarmDist -- ^ 4 divides the rank by the mean harmonic distance between extents (this is implemented only by ts_rank_cd)
+  | NormUniqueWords -- ^ 8 divides the rank by the number of unique words in document
+  | Norm1LogUniqueWords -- ^ 16 divides the rank by 1 + the logarithm of the number of unique words in document
+  | Norm1Self -- ^ 32 divides the rank by itself + 1
   deriving (Eq, Show, Enum, Bounded)
 
 normToInt :: NormalizationOption -> Int64