diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -1,1 +1,29 @@
-A **Fold1** datatype that consumes
+## Whats in this library?
+
+A pair of fold-like datatypes that consume
+[Producers](http://hackage.haskell.org/package/pipes-4.1.7/docs/Pipes.html#t:Producer)
+from [pipes](http://hackage.haskell.org/package/pipes) and can be constructed
+in a variety of ways, in particular from the more versatile folds in Gabriel
+Gonzalez's [foldl](http://hackage.haskell.org/package/foldl) package.
+
+The **Fold1** consumes a single **Producer**, while the **Fold2** datatype
+consumes two **Producer**s concurrently.
+
+## Why was this library created?
+
+I wanted a fold-like datatype for IO-based Producers that let me perform
+"bracketing" operations (the folds in foldl are push-based and do not allow
+that). 
+
+I also wanted to be able to fold two Producers concurrently (for example, take
+the piped stdout & stderr streams of an external process and merge the lines
+into a single file as they are produced).
+
+Finally, I wanted the fold-like datatype to have a "failure value" baked in.
+
+If you don't need any of that, you are better off using **pipes** and/or
+**foldl** by themselves. 
+
+## Where can I find working examples for this library?
+
+There are none yet.
diff --git a/pipes-transduce.cabal b/pipes-transduce.cabal
--- a/pipes-transduce.cabal
+++ b/pipes-transduce.cabal
@@ -1,5 +1,5 @@
 Name: pipes-transduce
-Version: 0.3.0.0
+Version: 0.3.0.1
 Cabal-Version: >=1.8.0.2
 Build-Type: Simple
 License: BSD3
@@ -9,7 +9,7 @@
 Maintainer: diaz_carrete@yahoo.com
 Bug-Reports: https://github.com/danidiaz/pipes-transduce/issues
 Synopsis: Interfacing pipes with foldl folds.
-Description: Grab-bag of functions for interfacing pipes with foldl folds.
+Description: A fold-like datatype for pipes Producers.
 Category: Control
 
 Extra-Source-Files:
@@ -24,21 +24,21 @@
     HS-Source-Dirs: src
     Build-Depends:
         base          >= 4        && < 5   ,
-        bytestring    >= 0.9.2.1  && < 0.11,
-        text          >= 0.11.2.0 && < 1.3 ,
+        bytestring    >= 0.9.2.1           ,
+        text          >= 0.11.2.0          ,
         transformers  >= 0.4.0.0           ,
-        bifunctors    == 5.*               ,
-        foldl         >= 1.1      && < 2   ,
+        bifunctors    >= 5.0               ,
+        foldl         >= 1.1               ,
         free          >= 4.0               ,
         pipes         == 4.*               ,
-        pipes-concurrency   >= 2.0.2 && < 3,
+        pipes-concurrency   >= 2.0.2       ,
         pipes-group   >= 1.0.1             ,
         pipes-parse                        ,
         pipes-safe                         ,
         pipes-text    >= 0.0.1.0           ,
         pipes-bytestring                   ,
         void          >= 0.6               ,
-        conceit       >= 0.3.2.0  && < 0.4.0.0,
+        conceit       >= 0.4.0.0           ,
         lens-family-core >= 1.1
     Exposed-Modules:
         Pipes.Transduce
@@ -57,7 +57,7 @@
       , free          == 4.*
       , pipes         == 4.*
       , doctest       >= 0.10.1
-      , foldl         >= 1.1      && < 2
+      , foldl         >= 1.1 
 
 test-suite tests
   type:           exitcode-stdio-1.0
diff --git a/src/Pipes/Transduce.hs b/src/Pipes/Transduce.hs
--- a/src/Pipes/Transduce.hs
+++ b/src/Pipes/Transduce.hs
@@ -527,6 +527,11 @@
 
 
 
+{-| 
+    A computation in 'IO' that consumes concurrently (and completely drains)
+    two 'Producer's of @b@ values, returning a value of type @a@, except when it
+    fails early with an error of type @e@.
+-}
 newtype Fold2 b1 b2 e a = Fold2 (Lift (Fold2_ b1 b2 e) a) deriving (Functor)
 
 data Fold2_ b1 b2 e a = 
@@ -631,9 +636,19 @@
         <*>
         Conceit (exhaustiveCont f2 producer2))
 
+{-|
+    Consume the producers concurrently, and each one independently of the other. 
+-}
 separated :: Fold1 b1 e r1 -> Fold1 b2 e r2 -> Fold2 b1 b2 e (r1,r2)
 separated f1 f2 = Fold2 (Other (separated_ (unLift . runFold1 $ f1) (unLift . runFold1 $ f2)))
 
+{-|
+    Consume the producers concurrently, delimiting groups in each producer,
+and writing the groups into a common 'Fold1'. 
+
+    Possible use: find lines in two text producers and combine them in a single
+stream, preserving the integrity of each individual line.
+-}
 combined :: Transducer Delimited b1 e x -> Transducer Delimited b2 e x -> Fold1 x e a -> Fold2 b1 b2 e a
 combined t1 t2 f = Fold2 (Other (Both (\producer1 producer2 -> do
    (outbox, inbox, seal) <- spawn' (bounded 1)
diff --git a/src/Pipes/Transduce/Text.hs b/src/Pipes/Transduce/Text.hs
--- a/src/Pipes/Transduce/Text.hs
+++ b/src/Pipes/Transduce/Text.hs
@@ -47,7 +47,7 @@
     Split the stream into lines, collect them into lazy 'Text' values, and pass
     them downstream. 
 
->>> PT.fold1  (transduce1 foldedLines (withFold L.list)) (mapM_ yield ["aa","aa\nbb","bb"]) 
+>>> PT.fold1 (transduce1 foldedLines (withFold L.list)) (mapM_ yield ["aa","aa\nbb","bb"]) 
 (["aaaa","bbbb"],())
 
 -}
@@ -59,8 +59,9 @@
     (lines_ (Pipes.Transduce.mapper id))
 
 {-| 
+    Split into lines, eliding newlines.
 
->>> PT.fold1  (transduce1 (concats (groups (\p -> yield "x" >> p) (lines_ (transducer id)))) intoLazyText) (mapM_ yield ["aa\n","bb"]) 
+>>> PT.fold1 (transduce1 (concats . groups (\p -> yield "x" *> p) . lines_ $ utf8x) intoLazyText) (mapM_ yield ["aa\n","bb"]) 
 ("xaaxbb",())
 
 -}
@@ -70,8 +71,9 @@
 lines_ sometrans = delimit (view Pipes.Text.lines) sometrans
 
 {-| 
+    Split into lines, preserving newlines.
 
->>> PT.fold1  (transduce1 (concats (groups (\p -> yield "x" >> p) (lines (transducer id)))) intoLazyText) (mapM_ yield ["aa\n","bb"]) 
+>>> PT.fold1 (transduce1 (concats . groups (\p -> yield "x" *> p) . lines $ utf8x) intoLazyText) (mapM_ yield ["aa\n","bb"]) 
 ("xaa\nxbb\n",())
 
 -}
@@ -96,7 +98,7 @@
 {-| Plug decoding functions from @pipes-text@ here. 
 
     __/BEWARE!/__ 
-    This 'Transducer' may throw 'DecodeError' here.
+    This 'Transducer' may throw 'DecodeError'.
     __/BEWARE!/__ 
 -}
 decoderx