Cleaned up developer doc

Proof'd everything and improved flow
Renamed advanced to events
Reordered sending/receiving
Added text type to languages for prism plugin

developer/receiving/async.md

@@ -1,5 +1,7 @@
 # Asynchronous Subscriptions
 
-Asynchronous subscriptions use callbacks of some form to notify an application when a message arrives. These subscriptions are usually easier to work with, but do represent some form of internal work and resource usage by the library. Check your libraries documentation for any resource usage associated with asynchronous subscriptions. The following example is the same as the previous one only with asynchronous code:
+Asynchronous subscriptions use callbacks of some form to notify an application when a message arrives. These subscriptions are usually easier to work with, but do represent some form of internal work and resource usage, i.e. threads, by the library. Check your library's documentation for any resource usage associated with asynchronous subscriptions.
+
+The following example subscribes to the subject `updates` and handles the incoming messages:
 
 !INCLUDE "../../_examples/subscribe_async.html"

developer/receiving/drain.md

@@ -1,6 +1,10 @@
 # Draining Connections and Subscriptions
 
-A new feature in the NATS client libraries is the ability to drain connections or subscriptions. Closing a connection, or unsubscribing from a subscription are generally considered immediate requests. Which means the library will halt messages in any pending queue or cache for subscribers. When you drain a subscription or connection, it will process any cached/pending messages before closing.
+A new feature being added across the NATS client libraries is the ability to drain connections or subscriptions. Closing a connection, or unsubscribing from a subscription are generally considered immediate requests. When you close or unsubscribe the library will halt messages in any pending queue or cache for subscribers. When you drain a subscription or connection, it will process any cached/pending messages before closing.
+
+Drain provides clients that use queue subscriptions with a way to bring down applications without losing any messages. A client can bring up a new queue member, drain and shut down the old queue member, all without losing messages sent to the old client. Without drain, there is the possibility of lost messages due to queue timing.
+
+The libraries can provide drain on a connection or on a subscriber, or both.
 
 For a connection the process is essentially:
 
@@ -9,9 +13,9 @@ For a connection the process is essentially:
   3. Flush any remaining messages
   4. Close
 
-!INCLUDE "../../_examples/drain_conn.html"
+As an example of draining a connection:
 
-Drain provides clients that use queue subscriptions with a way to bring down applications without losing any messages. A client can bring up a new queue member, drain and shut down the old queue member, all without losing messages sent to the old client. Without drain, there is the possibility of lost messages due to queue timing.
+!INCLUDE "../../_examples/drain_conn.html"
 
 The mechanics of drain for a subscription are simpler:
 

developer/receiving/intro.md

@@ -1,3 +1,9 @@
 # Receiving Messages
 
-Receiving messages with NATS can be very library dependent. Some languages, like Go or Java, can provide synchronous and asynchronous APIs, while others may only support one type of subscription. In all cases, the process of subscribing involves having the client library tell the NATS server that an application is interested in a particular subject. Under the covers, the client library will assign a unique id to each subscription. This id is used when the server sends messages to a specific subscription. Each subscription gets a unique id, so if the same connection is used multiple times for the same subject, the server will send multiple copies of the same message. When an application is done with a subscription it unsubscribes which tells the server to stop sending messages.
+Receiving messages with NATS can be very library dependent.
+
+Some languages, like Go or Java, provide synchronous and asynchronous APIs, while others may only support one type of subscription.
+
+In all cases, the process of subscribing involves having the client library tell the NATS server that an application is interested in a particular subject.
+
+Under the covers, the client library will assign a unique id to each subscription. This id is used when the server sends messages to a specific subscription. Each subscription gets a unique id, so if the same connection is used multiple times for the same subject, the server will send multiple copies of the same message. When an application is done with a subscription it unsubscribes which tells the server to stop sending messages.

developer/receiving/queues.md

@@ -1,6 +1,8 @@
 # Queue Subscriptions
 
-Using queues, from a subscription standpoint, is super easy. The application simply includes a queue name with the subscription.
+Subscribing to a queue group is only slightly different than subscribing to a subject alone. The application simply includes a queue name with the subscription. The effect of including the group is fairly major, since the server will now load balance messages between the members of the queue group, but the code differences are minimal.
+
+Keep in mind that the queue groups in NATS are dynamic and do not require any server configuration. You can almost think of a regular subscription as a queue group of 1, but it is probably not worth thinking too much about that.
 
 <div class="graphviz"><code data-viz="dot">
 digraph g {
@@ -18,7 +20,7 @@ digraph g {
 }
 </code></div>
 
-For example, to subscribe to the queue `workers` with the subject `updates`:
+As an example, to subscribe to the queue `workers` with the subject `updates`:
 
 !INCLUDE "../../_examples/subscribe_queue.html"
 

developer/receiving/reply.md

@@ -1,5 +1,7 @@
 # Replying to a Message
 
-Incoming messages have an optional reply-to field. If that field is set, it will contain a subject to which a reply is expected. In the publishing examples we sent a request for the current time. The following code will listen for that request and respond with the time.
+Incoming messages have an optional reply-to field. If that field is set, it will contain a subject to which a reply is expected.
+
+For example, the following code will listen for that request and respond with the time.
 
 !INCLUDE "../../_examples/subscribe_w_reply.html"

developer/receiving/structure.md

@@ -1,5 +1,7 @@
 # Receiving Structured Data
 
-In the publishing examples, we showed how to send JSON through NATS but you can receive encoded data as well. Each client library may provide tools to help with this encoding. The core traffic to the NATS server will always be byte arrays.
+Client libraries may provide tools to help receive structured data, like JSON. The core traffic to the NATS server will always be byte arrays. For libraries that don't provide helpers, you can always encode and decode data before sending the associated bytes to the NATS client.
+
+For example, to receive JSON you could do:
 
 !INCLUDE "../../_examples/subscribe_json.html"

developer/receiving/sync.md

@@ -1,6 +1,8 @@
 
 # Synchronous Subscriptions
 
-Synchronous subscriptions require the application to poll for messages. This type of subscription is easy to set-up and use, but requires the application to deal with looping if multiple messages are expected. For example, to subscribe to the subject `updates` and receive a single message you could do:
+Synchronous subscriptions require the application to poll for messages. This type of subscription is easy to set-up and use, but requires the application to deal with looping if multiple messages are expected. For situations where a single message is expected, synchronous subscriptions are sometimes easier to manage, depending on the language.
+
+For example, to subscribe to the subject `updates` and receive a single message you could do:
 
 !INCLUDE "../../_examples/subscribe_sync.html"

developer/receiving/unsub_after.md

@@ -1,10 +1,12 @@
 # Unsubscribing After a Specified Number of Messages
 
-NATS provides a special form of unsubscribe that is configured with a message count and takes effect when that many messages are sent to a subscriber. This mechanism is very useful if only a single message is expected. There are a few important things to know about auto unsubscribe. First, the message count you provide is the total message count for a subscriber. So if you unsubscribe with a count of 1, the server will stop sending messages to that subscription after it has received one. Or if the subscriber has already received one or more messages, the unsubscribe will be immediate. This action based on history can be confusing if you try to auto unsubscribe on a long running subscription, but is logical for a new one.
+NATS provides a special form of unsubscribe that is configured with a message count and takes effect when that many messages are sent to a subscriber. This mechanism is very useful if only a single message is expected.
+
+The message count you provide is the total message count for a subscriber. So if you unsubscribe with a count of 1, the server will stop sending messages to that subscription after it has received one message. If the subscriber has already received one or more messages, the unsubscribe will be immediate. This action based on history can be confusing if you try to auto unsubscribe on a long running subscription, but is logical for a new one.
 
 > Auto unsubscribe is based on the total messages sent to a subscriber, not just the new ones.
 
-Second, auto unsubscribe can also result in some tricky edge cases if a server cluster is used. The client will tell the server of the unsubscribe count when the application requests it. But if the client disconnects before the count is reached, it may have to tell another server of the remaining count. This dance between previous server notifications and new notifications on reconnect can result in unplanned behavior.
+Auto unsubscribe can also result in some tricky edge cases if a server cluster is used. The client will tell the server of the unsubscribe count when the application requests it. But if the client disconnects before the count is reached, it may have to tell another server of the remaining count. This dance between previous server notifications and new notifications on reconnect can result in unplanned behavior.
 
 Finally, most of the client libraries also track the max message count after an auto unsubscribe request. Which means that the client will stop allowing messages to flow even if the server has miscounted due to reconnects or some other failure in the client library.
 

developer/receiving/unsubscribing.md

@@ -1,5 +1,7 @@
 # Unsubscribing
 
-The client libraries provide a means to unsubscribe a previous subscription request. This process requires an interaction with the server, so for an asynchronous subscription there may be a small window of time where a message comes through as the unsubscribe is processed by the library. Ignoring that slight edge case, the client library will clean up any outstanding messages and tell the server that the subscription is no longer used.
+The client libraries provide a means to unsubscribe a previous subscription request.
+
+This process requires an interaction with the server, so for an asynchronous subscription there may be a small window of time where a message comes through as the unsubscribe is processed by the library. Ignoring that slight edge case, the client library will clean up any outstanding messages and tell the server that the subscription is no longer used.
 
 !INCLUDE "../../_examples/unsubscribe.html"

developer/receiving/wildcards.md

@@ -1,6 +1,8 @@
 # Wildcards
 
-There is no special code to subscribe with a wildcard subject. The main technique that may come in to play is to use the subject provided with the incoming message to determine what to do with the message.
+There is no special code to subscribe with a wildcard subject. Wildcards are a normal part of the subject name.
+
+However, there is a common technique that may come in to play when you use wildcards. This technique is to use the subject provided with the incoming message to determine what to do with the message.
 
 For example, you can subscribe using `*` and then act based on the actual subject.