doc: caution users against disabling buffering

Users may be tempted to disable buffering because it improves
synthetic benchmark performance.  Synthetic benchmarks are
just that and not indicative of what evil (or really crippled)
clients can do to a server.

1 files changed, 14 insertions, 2 deletions

diff --git a/Documentation/yahns_config.txt b/Documentation/yahns_config.txt
index 45bcfd9..d18263d 100644
--- a/Documentation/yahns_config.txt
+++ b/Documentation/yahns_config.txt
@@ -278,6 +278,11 @@ Ruby it is running under.
 
     HTTP request headers are always buffered in memory.
 
+    Do not be tempted to disable any buffering because it improves
+    numbers on a synthetic benchmark over a fast connection.
+    Slow, real-world clients can easily overwhelm servers without both
+    input and output buffering.
+
     Default: true
 
     The following OPTIONS may be specified:
@@ -418,12 +423,19 @@ Ruby it is running under.
 
     This enables or disables buffering of the HTTP response.  If enabled,
     buffering is only performed lazily.  In other words, buffering only
-    happens if socket buffers (in the kernel) are filled up.
+    happens if socket buffers (in the kernel) are filled up, and yahns
+    will continously try to flush the buffered data to the socket while
+    it is buffering.
 
-    Disabling output buffering is only recommended if all clients
+    Disabling output buffering is only recommended if ALL clients
     connecting to this application context are fast, trusted or
     you are willing and able to run many worker threads.
 
+    Do not be tempted to disable any buffering because it improves
+    numbers on a synthetic benchmark over a fast connection.
+    Slow, real-world clients can easily overwhelm servers without both
+    input and output buffering.
+
     If output buffering is disabled, client_timeout controls the maximum
     amount of time a worker thread will wait synchronously.