[doc] Housekeeping

wiki/1-Getting-started.md

@@ -179,13 +179,35 @@ client event-msg | `{:keys [event id ?data send-fn]}`
  * Server uses `chsk-send!` to send `event`s to _all_ the clients (browser tabs, devices, etc.) of a particular connected user by his/her [user-id](./2-Client-and-user-ids).
  * The server can also use an `event-msg`'s `?reply-fn` to _reply_ to a particular client `event` using an _arbitrary edn value_
 
-## Limitations
+## Channel socket state
 
-### Large transfers
+Each time the client's channel socket state changes, a client-side `:chsk/state` event will fire that you can watch for and handle like any other event.
+
+The event form is `[:chsk/state [<old-state-map> <new-state-map>]]` with the following possible state map keys:
+
+Key             | Value
+--------------- | --------------------------------------------------------
+:type           | e/o `#{:auto :ws :ajax}`
+:open?          | Truthy iff chsk appears to be open (connected) now
+:ever-opened?   | Truthy iff chsk handshake has ever completed successfully
+:first-open?    | Truthy iff chsk just completed first successful handshake
+:uid            | User id provided by server on handshake,    or nil
+:csrf-token     | CSRF token provided by server on handshake, or nil
+:handshake-data | Arb user data provided by server on handshake
+:last-ws-error  | `?{:udt _ :ev <WebSocket-on-error-event>}`
+:last-ws-close  | `?{:udt _ :ev <WebSocket-on-close-event> :clean? _ :code _ :reason _}`
+:last-close     | `?{:udt _ :reason _}`, with reason e/o `#{nil :requested-disconnect :requested-reconnect :downgrading-ws-to-ajax :unexpected}`
+
+# Limitations
+
+## Large transfers
 
 I recommend **not** using Sente to transfer large payloads (> 1MB).
 
-The reason is that Sente will by default operate over a WebSocket when possible. This is great for realtime bidirectional communications, but it does mean that there's a bottleneck on that socket.
+The reason is that Sente will by default operate over a WebSocket when possible. This is great for realtime bidirectional communications, but:
+
+1. WebSockets aren't ideal for large data transfers, and
+2. You'll have a bottleneck on that socket
 
 If a WebSocket connection is saturated dealing with a large transfer, other communications (e.g. notifications) won't be able to get through until the large transfer completes.
 
@@ -198,26 +220,7 @@ Instead, I recommend using Sente **only for small payloads** (<= 1MB) and for **
 
 (Sente includes a [util](https://taoensso.github.io/sente/taoensso.sente.cljs.html#var-ajax-lite) to make Ajax requests very easy).
 
-This way you're using the ideal tools for each job:
+This way you're using the ideal tool for each job:
 
 - Sente's realtime socket is reserved for realtime purposes
-- Dedicated Ajax requests are used for large transfers, and have access to normal browser HTTP caching, etc.
-
-## Channel socket state
-
-Each time the client's channel socket state changes, a client-side `:chsk/state` event will fire that you can watch for and handle like any other event.
-
-The event form is `[:chsk/state [<old-state-map> <new-state-map>]]` with the following possible state map keys:
-
-Key             | Value
---------------- | --------------------------------------------------------
-:type           | e/o `#{:auto :ws :ajax}`
-:open?          | Truthy iff chsk appears to be open (connected) now
-:ever-opened?   | Truthy iff chsk handshake has ever completed successfully
-:first-open?    | Truthy iff chsk just completed first successful handshake
-:uid            | User id provided by server on handshake,    or nil
-:csrf-token     | CSRF token provided by server on handshake, or nil
-:handshake-data | Arb user data provided by server on handshake
-:last-ws-error  | `?{:udt _ :ev <WebSocket-on-error-event>}`
-:last-ws-close  | `?{:udt _ :ev <WebSocket-on-close-event> :clean? _ :code _ :reason _}`
-:last-close     | `?{:udt _ :reason _}`, with reason e/o `#{nil :requested-disconnect :requested-reconnect :downgrading-ws-to-ajax :unexpected}`
+- Dedicated Ajax requests are used for large transfers, and have access to normal browser HTTP caching, etc.