Incorporating comments from PR

Signed-off-by: Matthias Hanel <mh@synadia.com>

SUMMARY.md

@@ -22,6 +22,7 @@
   * [Connecting to the Default Server](developing-with-nats/connecting/default_server.md)
   * [Connecting to a Specific Server](developing-with-nats/connecting/specific_server.md)
   * [Connecting to a Cluster](developing-with-nats/connecting/cluster.md)
+  * [Connection Name](developing-with-nats/connecting/name.md)
   * [Setting a Connect Timeout](developing-with-nats/connecting/connect_timeout.md)
   * [Ping/Pong Protocol](developing-with-nats/connecting/pingpong.md)
   * [Controlling the Client/Server Protocol](developing-with-nats/connecting/protocol.md)
@@ -29,8 +30,8 @@
 * [Automatic Reconnections](developing-with-nats/reconnect/README.md)
   * [Disabling Reconnect](developing-with-nats/reconnect/disable.md)
   * [Set the Number of Reconnect Attempts](developing-with-nats/reconnect/max.md)
-  * [Pausing Between Reconnect Attempts](developing-with-nats/reconnect/wait.md)
   * [Avoiding the Thundering Herd](developing-with-nats/reconnect/random.md)
+  * [Pausing Between Reconnect Attempts](developing-with-nats/reconnect/wait.md)
   * [Listening for Reconnect Events](developing-with-nats/reconnect/events.md)
   * [Buffering Messages During Reconnect Attempts](developing-with-nats/reconnect/buffer.md)
 * [Securing Connections](developing-with-nats/security/README.md)

developing-with-nats/connecting/name.md

@@ -1,6 +1,6 @@
 # Setting the Connection Name
 
-Connections can be assigned a name which will appear in some of the server monitoring data. This name is not required but can help in debugging and testing.
+Connections can be assigned a name which will appear in some of the server monitoring data. This name is not required, but is **highly recommended** as a friendly connection name will help in monitoring, error reporting, debugging, and testing.
 
 {% tabs %}
 {% tab title="Go" %}

developing-with-nats/connecting/pingpong.md

@@ -1,10 +1,14 @@
 # Ping/Pong Protocol
 
-The client and server use a simple PING/PONG protocol to check that either of them are still connected to the other. On a regular interval the client will ping the server, which responds with a pong. Once a configurable maximum of outstanding pings without a single pong reply is hit, the connection is closed as stale. Together these two values define a timeout for the connection. In the presence of traffic, such as messages or client side pings, the server will not initiate the PING/PONG interaction. 
+The client and server use a simple PING/PONG protocol to check that either of them are still connected to the other. On a regular interval the client will ping the server, which responds with a pong.
 
 ![](../../.gitbook/assets/pingpong.svg)
 
-If you have a connection that is going to be open a long time with few messages traveling on it, setting the PING interval and/or limit how many are outstanding, can control how quickly the client will be notified of a problem. However on connections with a lot of traffic, the client will often figure out there is a problem between PINGS, and as a result the default PING interval is often on the order of minutes. To set the interval to 20s and limit outstanding pings to 5, thus force a closed connection after 100s of inactivity:
+Once a configurable maximum of outstanding pings without a single pong reply is hit, the connection is closed as stale. Together these two values define a timeout for the connection which specifies how quickly the client will be notified of a problem. This will also help when there is a remote network partition where the operating system does not detect a socket error. Upon connection close the client will attempt to reconnect. When it knows about other server, these will be tried next.
+
+In the presence of traffic, such as messages or client side pings, the server will not initiate the PING/PONG interaction. 
+
+On connections with a lot of traffic, the client will often figure out there is a problem between PINGS, and as a result the default PING interval is often on the order of minutes. To set the interval to 20s and limit outstanding pings to 5, thus force a closed connection after 100s of inactivity:
 
 {% tabs %}
 {% tab title="Go" %}

developing-with-nats/events/slow.md

@@ -101,7 +101,7 @@ await nc.subscribe("updates", cb=cb, pending_bytes_limit=5*1024*1024, pending_ms
 
 {% tab title="Ruby" %}
 ```ruby
-# The Ruby NATS client currently does not have option to customize specify a subscribers pending limits.
+# The Ruby NATS client currently does not have option to specify a subscribers pending limits.
 ```
 {% endtab %}
 

developing-with-nats/receiving/README.md

@@ -6,4 +6,4 @@ Some languages, like Go or Java, provide synchronous and asynchronous APIs, whil
 
 In all cases, the process of subscribing involves having the client library tell the NATS system that an application is interested in a particular subject. When an application is done with a subscription it unsubscribes telling the server to stop sending messages.
 
-If a connection has multiple subscriptions using identical or overlapping subjects (say `foo` and `>`), the same message will be sent to the client multiple times.
+A client will receive a message for each matching subscription ,so if a connection has multiple subscriptions using identical or overlapping subjects (say `foo` and `>`) the same message will be sent to the client multiple times.

developing-with-nats/reconnect/events.md

@@ -1,7 +1,6 @@
 # Listening for Reconnect Events
 
 Because reconnect is primarily under the covers many libraries provide an event listener you can use to be notified of reconnect events. This event can be especially important for applications sending a lot of messages.
-- [ ] what do clients commonly do if reconnect is in progress and say a message is published? Block or error? 
 
 {% tabs %}
 {% tab title="Go" %}

developing-with-nats/reconnect/wait.md

@@ -1,6 +1,8 @@
 # Pausing Between Reconnect Attempts
 
-It doesn’t make much sense to try to connect to the same server over and over. To prevent this sort of thrashing, and wasted reconnect attempts, libraries provide a wait setting. Generally clients make sure that between two reconnect attempts to the **same** server at least a certain amount of time has passed. The concrete implementation depends on the library used.
+It doesn’t make much sense to try to connect to the same server over and over. To prevent this sort of thrashing, and wasted reconnect attempts, especially when using TLS, libraries provide a wait setting. Generally clients make sure that between two reconnect attempts to the **same** server at least a certain amount of time has passed. The concrete implementation depends on the library used.
+
+This setting not only prevents wasting client resources, it also alleviates a [_thundering herd_](random.md) situation when additional servers are not available.
 
 {% tabs %}
 {% tab title="Go" %}

developing-with-nats/security/nkey.md

@@ -1,6 +1,6 @@
 # Authenticating with an NKey
 
-The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call [NKeys](../../nats-server/configuration/securing_nats/auth_intro/nkey_auth.md). The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. (A printable private NKey is referred to as seed). This challenge-response ensures security by ensuring that the client has the private key, but also protects the private key from the server which never has to actually see it.
+The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call [NKeys](../../nats-server/configuration/securing_nats/auth_intro/nkey_auth.md). The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. (A printable private NKey is referred to as seed). This challenge-response ensures security by ensuring that the client has the private key, but also protects the private key from the server, which never has access to it!
 
 Handling challenge response may require more than just a setting in the connection options, depending on the client library.
 

developing-with-nats/security/token.md

@@ -1,6 +1,6 @@
 # Authenticating with a Token
 
-Tokens are basically random strings, much like a password, and can provide a simple authentication mechanism in some situations. However, tokens are only as safe as they are secret so other authentication schemes can provide more security in large installations.
+Tokens are basically random strings, much like a password, and can provide a simple authentication mechanism in some situations. However, tokens are only as safe as they are secret so other authentication schemes can provide more security in large installations. It is highly recommended to use one of the other NATS authentication mechanisms.
 
 For this example, start the server using:
 

developing-with-nats/tutorials/reqreply.md

@@ -35,9 +35,9 @@ This means that the NATS receiver client is listening for requests messages on t
 ### 5. In the other terminal, run the request client
 
 ```bash
-% go run nats-req/main.go help.please "some message"
+% go run nats-req/main.go help.please "I need help!"
 ```
 
-The NATS requestor client makes a request by sending the message "some message" on the “help.please” subject.
+The NATS requestor client makes a request by sending the message "I need help!" on the “help.please” subject.
 
 The NATS receiver client receives the message, formulates the reply \("OK, I CAN HELP!!!"\), and sends it to the inbox of the requester.