diff --git a/bench/Main.hs b/bench/Main.hs
new file mode 100644
--- /dev/null
+++ b/bench/Main.hs
@@ -0,0 +1,10 @@
+module Main where
+
+import Criterion.Main
+import Data.Duration
+
+main :: IO ()
+main = defaultMain
+  [ bgroup "to human"
+    [ bench "small" $ nf humanReadableDuration 0.123456
+    , bench "Basic" $ nf humanReadableDuration 987654321.123456 ]]
diff --git a/human-readable-duration.cabal b/human-readable-duration.cabal
--- a/human-readable-duration.cabal
+++ b/human-readable-duration.cabal
@@ -1,5 +1,5 @@
 name:                human-readable-duration
-version:             0.2.0.0
+version:             0.2.0.1
 synopsis:            Provide duration helper
 homepage:            http://github.com/yogsototh/human-readable-duration#readme
 license:             BSD3
@@ -26,17 +26,30 @@
 library
   hs-source-dirs:      src
   exposed-modules:     Data.Duration
+                       Data.Duration.Tutorial
   build-depends:       base >= 4.7 && < 5
   default-language:    Haskell2010
 
--- test-suite human-readable-duration-test
---   type:                exitcode-stdio-1.0
---   hs-source-dirs:      test
---   main-is:             Spec.hs
---   build-depends:       base
---                      , human-readable-duration
---   ghc-options:         -threaded -rtsopts -with-rtsopts=-N
---   default-language:    Haskell2010
+test-suite human-readable-duration-test
+  type:                exitcode-stdio-1.0
+  hs-source-dirs:      test
+  main-is:             Spec.hs
+  build-depends:       base >= 4.7 && < 5
+                     , human-readable-duration
+                     , doctest >= 0.9.12
+                     , time >= 1.5.0.0
+  ghc-options:         -O2 -Wall
+  default-language:    Haskell2010
+
+benchmark hrd-bench
+  type: exitcode-stdio-1.0
+  hs-source-dirs: bench
+  main-is: Main.hs
+  ghc-options: -O2 -Wall -threaded
+  default-language: Haskell2010
+  build-depends: base >= 4.7 && < 5
+               , criterion >= 1.1.0.0
+               , human-readable-duration
 
 source-repository head
   type:     git
diff --git a/src/Data/Duration.hs b/src/Data/Duration.hs
--- a/src/Data/Duration.hs
+++ b/src/Data/Duration.hs
@@ -1,3 +1,18 @@
+ {-| This is a minimal Haskell library to display duration.
+
+  @
+  > let duration = 2 * ms + 3 * oneSecond + 2 * minute + 33*day + 2*year
+  > humanReadableDuration duration
+  "2 years 33 days 2 min 3s 2ms"
+  > getYears duration
+  2
+  > getDays duration
+  763
+  > getMs duration
+  65923323002
+  @
+
+-}
 module Data.Duration
     ( humanReadableDuration
     , humanReadableDuration'
@@ -19,11 +34,14 @@
 
 import Data.Fixed (Fixed(..), Micro, div', mod')
 
--- | `humanReadableDuration` take some time in micro-second precision and render a human readable duration.
---
---    > let duration = 2 * ms + 3 * oneSecond + 2 * minute + 33*day + 2*year
---    > humanReadableDuration duration
---    > -- will return: "2 years 33 days 2 min 3s 32ms"
+{- | `humanReadableDuration` take some time in micro-second precision and render a human readable duration.
+
+>>> let duration = 2 * ms + 3 * oneSecond + 2 * minute + 33*day + 2*year
+>>> duration
+65923323.002000
+>>> humanReadableDuration duration
+"2 years 33 days 2 min 3s 2ms"
+-}
 humanReadableDuration :: Micro -> String
 humanReadableDuration n
   | n < oneSecond = let mi = getMs      n in if mi > 0 then show mi ++ "ms" else ""
@@ -35,6 +53,10 @@
 
 -- | Wrapper around any `Real` input, which works for `DiffTime` and
 -- `NominalDiffTime` from the time library, or a `Double` of seconds.
+--
+-- >>> import Data.Time.Clock
+-- >>> humanReadableDuration' (secondsToDiffTime 10)
+-- "10s "
 humanReadableDuration' :: Real a => a -> String
 humanReadableDuration' = humanReadableDuration . realToFrac
 
@@ -42,27 +64,55 @@
 -- Durations
 --------------------------------------------------------------------------------
 
--- | number of micro seconds in one millisecond
+-- | one millisecond (@0.001@)
+--
+-- >>> ms
+-- 0.001000
+-- >>> 1000 * ms
+-- 1.000000
 ms :: Micro
 ms = MkFixed 1000
 
--- | number of micro seconds in one second
+-- | one second (@1@)
+--
+-- >>> oneSecond / ms
+-- 1000.000000
+-- >>> oneSecond
+-- 1.000000
 oneSecond :: Micro
 oneSecond = 1000 * ms
 
--- | number of micro seconds in one minute
+-- | number of seconds in one minute
+--
+-- >>> minute / oneSecond
+-- 60.000000
+-- >>> minute / ms
+-- 60000.000000
 minute :: Micro
 minute = 60 * oneSecond
 
--- | number of micro seconds in one hour
+-- | number of seconds in one hour
+--
+-- >>> hour / minute
+-- 60.000000
+-- >>> hour / oneSecond
+-- 3600.000000
 hour :: Micro
 hour = 60 * minute
 
--- | number of micro seconds in one day
+-- | number of seconds in one day
+--
+-- >>> day / hour
+-- 24.000000
+-- >>> day / oneSecond
+-- 86400.000000
 day :: Micro
 day = 24 * hour
 
--- | number of micro seconds in one year
+-- | number of seconds in one year
+--
+-- >>> year / day
+-- 365.000000
 year :: Micro
 year = 365 * day
 
@@ -70,25 +120,57 @@
 -- Retrieve some durations
 --------------------------------------------------------------------------------
 -- | number of milli seconds given a duration in micro seconds
+--
+-- >>> getMs 1
+-- 1000
+-- >>> getMs 1.618033
+-- 1618
 getMs :: Micro -> Integer
 getMs n = n `div'` ms
 
 -- | number of seconds given a duration in micro seconds
+--
+-- >>> getSeconds 1
+-- 1
+-- >>> getSeconds 1.618033
+-- 1
 getSeconds :: Micro -> Integer
 getSeconds n = n `div'` oneSecond
 
 -- | number of minutes given a duration in micro seconds
+--
+-- >>> getMinutes 60
+-- 1
+-- >>> getMinutes 59
+-- 0
 getMinutes :: Micro -> Integer
 getMinutes n = n `div'` minute
 
 -- | number of hours given a duration in micro seconds
+--
+-- >>> getHours 3600
+-- 1
+-- >>> getHours (60 * minute)
+-- 1
+-- >>> getHours (2 * day)
+-- 48
 getHours :: Micro -> Integer
 getHours n = n `div'` hour
 
 -- | number of days given a duration in micro seconds
+--
+-- >>> getDays (10 * day)
+-- 10
+-- >>> getDays (240 * hour)
+-- 10
 getDays :: Micro -> Integer
 getDays n = n `div'` day
 
 -- | number of years given a duration in micro seconds
+--
+-- >>> getYears (720 * day)
+-- 1
+-- >>> getYears (740 * day)
+-- 2
 getYears :: Micro -> Integer
 getYears n = n `div'` year
diff --git a/src/Data/Duration/Tutorial.hs b/src/Data/Duration/Tutorial.hs
new file mode 100644
--- /dev/null
+++ b/src/Data/Duration/Tutorial.hs
@@ -0,0 +1,48 @@
+ {-# OPTIONS_GHC -fno-warn-unused-imports #-}
+{-|
+ Use @human-readable-duration@ if you want to replace
+ "1002012 seconds left"
+ by the easier to read:
+ "11 days 14 hours 20 min 12s left"
+
+ But also if you want to manipulate time duration easily
+ by using seconds, minutes, hours and days.
+ Typically if you prefer to write:
+
+ @
+ x + (5 * oneSecond) + (2 * minute) + (1 * day)
+ @
+
+ instead of
+
+ @
+ x + 5 * 2*60 * 1*60*60*24
+ @
+-}
+module Data.Duration.Tutorial (
+  -- * Introduction
+  -- $introduction
+  ) where
+
+import Data.Duration
+
+
+{- $introduction
+
+So here how you use it:
+
+ >>> humanReadableDuration 1002012.002
+ "11 days 14 hours 20 min 12s 2ms"
+
+ >>> humanReadableDuration $ (4 * hour) + (2 * minute) + (3 * ms)
+ "4 hours 2 min 3ms"
+
+ And one nice thing you could do:
+
+ >>> let duration1 = (4 * hour) + (2 * minute) + (3 * ms)
+ >>> let duration2 = (8 * hour) + (33 * minute) + (5 * oneSecond)
+ >>> humanReadableDuration (4 * duration1 + 2 * duration2)
+ "1 days 9 hours 14 min 10s 12ms"
+
+ Happy hacking.
+-}
diff --git a/test/Spec.hs b/test/Spec.hs
new file mode 100644
--- /dev/null
+++ b/test/Spec.hs
@@ -0,0 +1,7 @@
+module Main where
+
+import Test.DocTest
+
+main :: IO ()
+main = doctest [ "src/Data/Duration.hs"
+               , "src/Data/Duration/Tutorial.hs"]