Explaining how partitioning works.

README.md

@@ -77,6 +77,28 @@ Padding can be achieved using the `pad` function:
 {false {:sum 16256, :mean 127, :count 128}, true {:sum 16384, :mean 128, :count 128}}
 ```
 
+## On Partitioning
+
+Both `by-key` and `partition` takes a transducer as parameter. This transducer is used to further process each partition.
+
+It's worth noting that all transformed outputs are subsequently interleaved. See:
+
+```clj
+=> (sequence (x/partition 2 1 identity) (range 8))
+(0 1 1 2 2 3 3 4 4 5 5 6 6 7 7)
+=> (sequence (x/by-key odd? identity) (range 8))
+([false 0] [true 1] [false 2] [true 3] [false 4] [true 5] [false 6] [true 7])
+```
+
+That's why most of the time the last stage of the sub-transducer will be a `x/reduce` or a `x/into`:
+
+```clj
+=> (sequence (x/partition 2 1 (x/into [])) (range 8))
+([0 1] [1 2] [2 3] [3 4] [4 5] [5 6] [6 7] [7])
+=> (sequence (x/by-key odd? (x/into [])) (range 8))
+([false [0 2 4 6]] [true [1 3 5 7]])
+```
+
 ## License
 
 Copyright © 2015 Christophe Grand