add note about pipelining

docsite/rst/intro_configuration.rst

@@ -561,12 +561,31 @@ cause scp to be used to transfer remote files instead::
 There's really no reason to change this unless problems are encountered, and then there's also no real drawback
 to managing the switch.  Most environments support SFTP by default and this doesn't usually need to be changed.
 
+
+.. _pipelining:
+
+pipelining
+==========
+
+Enabling pipelining reduces the number of SSH operations required to
+execute a module on the remote server, by executing many ansible modules without actual file transfer. 
+This can result in a very significant performance improvement when enabled, however when using "sudo:" operations you must
+first disable 'requiretty' in /etc/sudoers on all managed hosts.
+
+By default, this option is disabled to preserve compatibility with
+sudoers configurations that have requiretty (the default on many distros), but is highly
+recommended if you can enable it, eliminating the need for :doc:`playbooks_acceleration`::
+
+    pipelining=False
+
 .. _accelerate_settings:
 
 Accelerate Mode Settings
 ------------------------
 
-Under the [accelerate] header, the following settings are tunable for :doc:`playbooks_acceleration`
+Under the [accelerate] header, the following settings are tunable for :doc:`playbooks_acceleration`.  Acceleration is 
+a useful performance feature to use if you cannot enable :ref:`ssh_pipelining` in your environment, but is probably
+not needed if you can.
 
 .. _accelerate_port:
 

docsite/rst/playbooks_acceleration.rst

@@ -3,6 +3,19 @@ Accelerated Mode
 
 .. versionadded:: 1.3
 
+.. note:
+
+   Are you running Ansible 1.5 or later?  If so, you may not need accelerate mode due to a new feature called "SSH pipelining"
+
+   For users on 1.5 and later, accelerate mode only makes sense if you are (A) are managing from an Enterprise Linux 6 or earlier host
+   and still are on paramiko, or (B) can't enable TTYs with sudo as described in the pipelining section of 
+   ref:`intro_configuration`.  
+
+   If you can use it, the pipelining feature in Ansible reduces the amount of files transferred over the wire, 
+   making everything much more efficient. If you can enable pipelining in ansible.cfg, it is
+   preferable to accelerate mode in most cases and requires fewer moving parts.  Accelerate mode remains around in support of EL6
+   control machines and other constrained environments.
+
 While OpenSSH using the ControlPersist feature is quite fast and scalable, there is a certain small amount of overhead involved in
 using SSH connections.  While many people will not encounter a need, if you are running on a platform that doesn't have ControlPersist support (such as an EL6 control machine), you'll probably be even more interested in tuning options.