diff --git a/ChangeLog b/ChangeLog
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+v0.1.1.1
+
+	* Improve documentation.
+
 v0.1.1.0
 
 	* Export data constructors for UserMapping & GroupMapping.
diff --git a/System/Linux/Namespaces.hsc b/System/Linux/Namespaces.hsc
--- a/System/Linux/Namespaces.hsc
+++ b/System/Linux/Namespaces.hsc
@@ -19,6 +19,7 @@
 of the same process. The threaded RTS makes it is hard to predict what
 OS thread will be used to run the haskell threads. Therefore, using this
 module in such applications will result in unpredictable behavior.
+Similarly, using this module in @ghci@ is also problematic.
 -}
 
 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
@@ -29,15 +30,20 @@
       Namespace(..)
     , unshare
     , setNamespace
+
     -- * Utility functions
     , enterNamespace
     , NamespaceID
     , getNamespaceID
+
     -- * User/Group mappings
     , UserMapping(..)
     , GroupMapping(..)
     , writeUserMappings
     , writeGroupMappings
+
+    -- * Example
+    -- $example
     ) where
 
 #define _GNU_SOURCE
@@ -200,3 +206,34 @@
 
 foreign import ccall unsafe "setns"
     c_setns :: Fd -> CInt -> IO CInt
+
+--------------------------------------------------------------------------------
+
+-- $example
+-- Here's an example of creating a new network namespace. We also create
+-- a user namespace. This allows us to execute the program as an
+-- unprivileged user.
+--
+-- > import System.Process
+-- > import System.Posix.User
+-- > import System.Linux.Namespaces
+-- >
+-- > main :: IO ()
+-- > main = do
+-- >     putStrLn "*** Network interfaces in the parent namespace ***"
+-- >     callCommand "ip addr"
+-- >     putStrLn ""
+-- >
+-- >     -- find the uid, we must do that before unshare
+-- >     uid <- getEffectiveUserID
+-- >
+-- >     unshare [User, Network]
+-- >     -- map current user to user 0 (i.e. root) inside the namespace
+-- >     writeUserMappings Nothing [UserMapping 0 uid 1]
+-- >
+-- >     -- enable the loopback interface
+-- >     -- we can do that because we are root inside the namespace
+-- >     callCommand "ip link set dev lo up"
+-- >
+-- >     putStrLn "*** Network interfaces in the new namespace ***"
+-- >     callCommand "ip addr"
diff --git a/linux-namespaces.cabal b/linux-namespaces.cabal
--- a/linux-namespaces.cabal
+++ b/linux-namespaces.cabal
@@ -1,5 +1,5 @@
 name:                linux-namespaces
-version:             0.1.1.0
+version:             0.1.1.1
 synopsis:            Create new or enter an existing linux namespaces
 description:
   This library provides bindings to the @unshare(2)@ and @setns(2)@ linux