Reword and add links

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

developing-with-nats/reconnect/README.md

@@ -2,7 +2,4 @@
 
 Most, if not all, of the client libraries will reconnect to the NATS system if they are disconnected for any reason. The reconnect logic can differ by library, so check your client library's documentation.
 
-In general, the client will try to connect to all of the servers it knows about, either through the URLs provided in the `connect` call or the URLs provided by the NATS system itself. The NATS system will inform clients of new endpoints that can be used to reconnect. The library may have several options to help control reconnect behavior.
-
-The list of servers used during reconnect is library dependent, but generally is constructed from connect function/options and the list of servers provided by the NATS system itself. This feature allows NATS applications and the NATS system itself to self heal and reconfigure itself with no additional configuration or intervention.
-
+In general, the client will try to re-connect to one of the servers it knows about, either through the URLs provided in the `connect` call or the URLs provided by the NATS system during erlier connects. This feature allows NATS applications and the NATS system itself to self heal and reconfigure itself with no additional configuration or intervention. The library may have several options to help control reconnect behavior, notify about recennect state and inform about new server.

developing-with-nats/reconnect/buffer.md

@@ -2,9 +2,9 @@
 
 The NATS client libraries try as much as possible to be fire and forget. One of the features that may be included in the library you are using is the ability to buffer outgoing messages when the connection is down.
 
-During a short reconnect, these client can allow applications to publish messages that, because the server is offline, will be cached in the client. The library will then send those messages on reconnect. When the maximum reconnect buffer is reached, messages will no longer be publishable by the client.
+During a short reconnect, these client can allow applications to publish messages that, because the server is offline, will be cached in the client. The library will then send those messages once reconnected. When the maximum reconnect buffer is reached, messages will no longer be publishable by the client and an error will be returned.
 
-Be aware, while the message appears to be sent to the application it is possible that it is never sent because the connection is never remade. Your applications should use patterns like acknowledgements to ensure delivery.
+Be aware, while the message appears to be sent to the application it is possible that it is never sent because the connection is never remade. Your applications should use patterns like [acknowledgements](../../nats-concepts/acks.md) to ensure delivery.
 
 For clients that support this feature, you are able to configure the size of this buffer with bytes, messages or both.
 

developing-with-nats/reconnect/events.md

@@ -1,6 +1,7 @@
 # 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/max.md

@@ -1,6 +1,6 @@
 # Set the Number of Reconnect Attempts
 
-Applications can set the maximum reconnect attempts. Generally, this will limit the actual number of attempts total, but check your library documentation. For example, in Java, if the client knows about 3 servers and the maximum reconnects is set to 2, it will not try all of the servers. On the other hand, if the maximum is set to 6 it will try all of the servers twice before considering the reconnect a failure and closing.
+Applications can set the maximum reconnect attempts per server. This includes server provided to the clients connect call, as well as server the client discovered through other server. Once re-connect to a server failed the specified amount of times in a row, it will be removed from the connect list. After a succesfull re-connect to a server, the client will reset this servers failed reconnect attempt count. If a server was removed from the connect list, it can be re-discovered on connect. This effectively resets the connect attempt count as well. If the client runs out of servers to re-connect, it will close the connection and [raise an error](events.md). 
 
 {% tabs %}
 {% tab title="Go" %}
@@ -71,7 +71,6 @@ end
 // will throw an exception if connection fails
 let nc = await connect({
     maxReconnectAttempts: 10,
-    servers: ["nats://demo.nats.io:4222"]
 });
 nc.close();
 ```

developing-with-nats/reconnect/random.md

@@ -2,7 +2,7 @@
 
 When a server goes down, there is a possible anti-pattern called the _Thundering Herd_ where all of the clients try to reconnect immediately, thus creating a denial of service attack. In order to prevent this, most NATS client libraries randomize the servers they attempt to connect to. This setting has no effect if only a single server is used, but in the case of a cluster, randomization, or shuffling, will ensure that no one server bears the brunt of the client reconnect attempts.
 
-However, if you want to disable the randomization process, so that servers are always checked in the same order, you can do that in most libraries with a connection options:
+However, if you want to disable the randomization process for connect and re-connect, so that servers are always checked in the same order, you can do that in most libraries with a connection option:
 
 {% tabs %}
 {% tab title="Go" %}
@@ -39,7 +39,7 @@ nc.close();
 {% tab title="JavaScript" %}
 ```javascript
 let nc = NATS.connect({
-    noRandomize: false,
+    noRandomize: true,
     servers: ["nats://127.0.0.1:4443",
         "nats://demo.nats.io:4222"
     ]
@@ -82,7 +82,7 @@ end
 ```typescript
 // will throw an exception if connection fails
 let nc = await connect({
-    noRandomize: false,
+    noRandomize: true,
     servers: ["nats://127.0.0.1:4443",
         "nats://demo.nats.io:4222"
     ]

developing-with-nats/reconnect/wait.md

@@ -1,6 +1,6 @@
 # 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. This setting will pause the reconnect logic if the same server is being tried multiple times **in a row**. In the previous example, if you have 3 servers and 6 attempts, the Java library would loop over the three servers. If none were connectable, it will then try all three again. However, the Java client doesn’t wait between each attempt, only when trying the same server again, so in that example the library may never wait. If on the other hand, you only provide a single server URL and 6 attempts, the library will wait between each attempt.
+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.
 
 {% tabs %}
 {% tab title="Go" %}
@@ -33,7 +33,6 @@ nc.close();
 {% tab title="JavaScript" %}
 ```javascript
 let nc = NATS.connect({
-    reconnectTimeWait: 10 * 1000, //10s
     servers: ["nats://demo.nats.io:4222"]
 });
 ```
@@ -70,7 +69,6 @@ end
 ```typescript
 // will throw an exception if connection fails
 let nc = await connect({
-    reconnectTimeWait: 10*1000, //10s
     servers: ["nats://demo.nats.io:4222"]
 });
 nc.close();