Expand heartbeats guide to cover some of the commonly asked questions

Author: michaelklishin

site/heartbeats.xml

@@ -3,8 +3,8 @@
 Copyright (c) 2007-2016 Pivotal Software, Inc.
 
 All rights reserved. This program and the accompanying materials
-are made available under the terms of the under the Apache License, 
-Version 2.0 (the "License”); you may not use this file except in compliance 
+are made available under the terms of the under the Apache License,
+Version 2.0 (the "License”); you may not use this file except in compliance
 with the License. You may obtain a copy of the License at
 
 http://www.apache.org/licenses/LICENSE-2.0
@@ -102,6 +102,26 @@ cf.RequestedHeartbeat = 60;
 </pre>
     </doc:section>
 
+    <doc:section name="false-positives">
+      <doc:heading>Low Timeout Values and False Positives</doc:heading>
+      <p>
+        Setting heartbeat timeout value too low can lead to false
+        positives (peer being considered unavailable while it really
+        isn't the case) due to transient network congestion,
+        short-lived server flow control, and so on.
+
+        This should be taken into consideration when picking a timeout
+        value.
+      </p>
+      <p>
+        Several years worth of feedback from the users and client
+        library maintainers suggest that values lower than 5 seconds
+        are fairly likely to cause false positives, and values of 1
+        second or lower are very likely to do so. Values within the 5
+        to 20 seconds range are optimal for most environments.
+      </p>
+    </doc:section>
+
     <doc:section name="stomp">
       <doc:heading>Heartbeats in STOMP</doc:heading>
       <p>
@@ -114,5 +134,17 @@ cf.RequestedHeartbeat = 60;
       </p>
     </doc:section>
 
+    <doc:section name="shovel-and-federation">
+      <doc:heading>Heartbeats in Shovel and Federation Plugins</doc:heading>
+      <p>
+        <a href="/shovel.html">Shovel</a> and <a href="/federation.html">Federation</a> plugins open Erlang client
+        connections to RabbitMQ nodes under the hood. As such, they can be configured
+        to use a desired heartbeat value.
+      </p>
+      <p>
+        Please refer to the <a href="/uri-query-parameters.html">AMQP 0-9-1 URI query parameters reference</a>
+        for details.
+      </p>
+    </doc:section>
   </body>
 </html>

site/uri-query-parameters.xml

@@ -111,15 +111,15 @@ limitations under the License.
       <tr>
         <td><code>heartbeat</code></td>
         <td>
-          <a href="/heartbeats.html">Heartbeat</a> value (in seconds)
+          <a href="/heartbeats.html">Heartbeat</a> timeout value in seconds (an integer)
           to negotiate with the server.
         </td>
       </tr>
       <tr>
         <td><code>connection_timeout</code></td>
         <td>
-          Time (in seconds) to wait while establishing a connection
-          before giving up.
+          Time in seconds (an integer) to wait while establishing a TCP connection
+          to the server before giving up.
         </td>
       </tr>
       <tr>