inform better about serial mode

README.rst

@@ -70,16 +70,22 @@ appropriately.
 VOID serial(BOOL serial=0)
 --------------------------
 
+Activates serial mode if the argument is ``true``.
+
 To be called from vcl_deliver {} only, the default argument is
 ``false``.
 
-If called with a ``true`` argument, no new threads will be started
-from this request and all ESI subrequests at the next level only will
-be processed by the current thread.
+In serial mode, no new threads will be started from this request and
+all ESI subrequests at the next level only will be processed by the
+current thread.
 
 In other words, the setting only affects include processing for the
 current response body.
 
+It is strongly recommended to _not_ use serial mode from ESI level 0
+because the ESI level 0 thread is responsible for sending available
+data to the client.
+
 .. _vmod_pesi.version:
 
 STRING version()

src/vdp_pesi.vcc

@@ -56,16 +56,22 @@ appropriately.
 
 $Function VOID serial(BOOL serial=0)
 
+Activates serial mode if the argument is ``true``.
+
 To be called from vcl_deliver {} only, the default argument is
 ``false``.
 
-If called with a ``true`` argument, no new threads will be started
-from this request and all ESI subrequests at the next level only will
-be processed by the current thread.
+In serial mode, no new threads will be started from this request and
+all ESI subrequests at the next level only will be processed by the
+current thread.
 
 In other words, the setting only affects include processing for the
 current response body.
 
+It is strongly recommended to _not_ use serial mode from ESI level 0
+because the ESI level 0 thread is responsible for sending available
+data to the client.
+
 $Function STRING version()
 
 Return the version string for this VDP.