Guidance on pub/sub completion order

Docs/Basics.md

@@ -73,6 +73,8 @@ Separately (and often in a separate process on a separate machine) you can publi
 
 This will (virtually instantaneously) write `"hello"` to the console of the subscribed process. As before, both channel-names and messages can be binary.
 
+Please also see [Pub / Sub Message Order](https://github.com/StackExchange/StackExchange.Redis/blob/master/Docs/PubSubOrder.md) for guidance on sequential versus concurrent message processing.
+
 Accessing individual servers
 ---
 

Docs/Docs.csproj

@@ -47,6 +47,7 @@
     <None Include="Basics.md" />
     <None Include="Events.md" />
     <None Include="ExecSync.md" />
+    <None Include="PubSubOrder.md" />
     <None Include="PipelinesMultiplexers.md" />
     <None Include="Transactions.md" />
   </ItemGroup>

Docs/PubSubOrder.md

+Pub/Sub Message Order
+===
+
+When using the pub/sub API, there is a decision to be made as to whether messages from the same connection should be processed *sequentially* vs *concurrently*.
+
+Processing them sequentially means that you don't need to worry (quite as much) about thread-safety, and means that you preserve the order of events -
+they will be processed in exactly the same order in which they are received (via a queue) - but as a consequence it means that messages can delay each-other.
+
+The other option is *concurrent* processing. This makes **no specific guarantees** about the order in which work gets processed, and your code is entirely
+responsible for ensuring that concurrent messages don't corrupt your internal state - but it can be significantly faster and much more scalable.
+This works *particularly* well if messages are generally unrelated.
+
+For safety, **the default is sequential**; however, it is strongly recommended that you use concurrent processing whenever possible. This is a simple change:
+
+    multiplexer.PreserveAsyncOrder = false;
+
+The reason that this is not a *configuration* option is that whether it is appropriate to do this depends *entirely* on the code that is subscribing to
+messages.
\ No newline at end of file

README.md

@@ -31,6 +31,7 @@ Documentation
 - [Keys, Values and Channels](https://github.com/StackExchange/StackExchange.Redis/blob/master/Docs/KeysValues.md) - discusses the data-types used on the API
 - [Transactions](https://github.com/StackExchange/StackExchange.Redis/blob/master/Docs/Transactions.md) - how atomic transactions work in redis
 - [Events](https://github.com/StackExchange/StackExchange.Redis/blob/master/Docs/Events.md) - the events available for logging / information purposes
+- [Pub/Sub Message Order](https://github.com/StackExchange/StackExchange.Redis/blob/master/Docs/PubSubOrder.md) - advice on sequential and concurrent processing
 
 Questions and Contributions
 ---