diff --git a/doc/userdoc.org b/doc/userdoc.org
index 169f041f3e45056dd762db057a5269591d363f5d..96bcd3f7690a8906ec4b3af8a6f2e5146fad1c33 100644
--- a/doc/userdoc.org
+++ b/doc/userdoc.org
@@ -3431,6 +3431,30 @@ In this example, we set three arrays defined at all nodes, all the
 - ~face_values~ interpolates ~f~ at the centers of the faces of ~m~,
 - ~cell_values~ interpolates ~f~ at the centers of the cells of ~m~.
 
+***** ~load_balance:mesh -> mesh~
+
+Creates a new partition of a mesh in parallel (~MPI~).
+#+BEGIN_SRC pugs :exports both :results none
+  import mesh;
+
+  let m1:mesh, m1 = cartesianMesh([0,0], [1,1], (10,10));
+  let m2:mesh, m2 = load_balance(m1);
+#+END_SRC
+In this example the mesh ~m2~ is a new parallel partition of the mesh
+~m1~. This implies that the two meshes, while being identical from the
+mathematical point of view, are now different (and are not defined on
+a same connectivity: the connectivity is actually balanced).
+
+Discrete functions defined on ~m1~ are *not* implicitly transferred on the
+mesh ~m2~! The function ~load_balance:(Vh)->(Vh)~ must be used to perform
+mesh and data load balancing.
+
+#+BEGIN_note
+To simplify development of large calculations. A sequential call of
+this function has the same effect: the mesh and its connectivity are
+copied!
+#+END_note
+
 ***** ~transform: mesh*function -> mesh~
 
 This function allows to compute a new mesh as the transformation of a