Minor doc updates

website/source/docs/configuration/index.html.md

@@ -37,7 +37,7 @@ sending a SIGHUP to the server process. These are denoted below.
 
 ## Parameters
 
-- `storage` <tt>([StorageBackend][storage-backend]: \<required\>)</tt> -
+- `storage` <tt>([StorageBackend][storage-backend]: \<required\>)</tt> –
   Configures the storage backend where Vault data is stored. Please see the
   [storage backends documentation][storage-backend] for the full list of
   available storage backends. Running Vault in HA mode would require
@@ -47,7 +47,7 @@ sending a SIGHUP to the server process. These are denoted below.
   configured with a backend that supports HA, along with corresponding HA
   options.
 
-- `ha_storage` <tt>([StorageBackend][storage-backend]: nil)</tt> - Configures
+- `ha_storage` <tt>([StorageBackend][storage-backend]: nil)</tt> – Configures
   the storage backend where Vault HA coordination will take place. This must be
   an HA-supporting backend. If not set, HA will be attempted on the backend
   given in the `storage` parameter. This parameter is not required if the
@@ -58,7 +58,7 @@ sending a SIGHUP to the server process. These are denoted below.
   Vault cluster. If omitted, Vault will generate a value. When connecting to
   Vault Enterprise, this value will be used in the interface.
 
-- `listener` <tt>([Listener][listener]: \<required\>)</tt> - Configures how
+- `listener` <tt>([Listener][listener]: \<required\>)</tt> – Configures how
   Vault is listening for API requests.
 
 - `cache_size` `(string: "32k")` – Specifies the size of the read cache used by

website/source/docs/internals/replication.html.md

@@ -144,6 +144,25 @@ Vault uses the merkle index as the source of truth, allowing the WAL streams to
 be completely distinct and unsynchronized.  This simplifies administration of
 Vault Replication for operators.
 
+# Caveats
+
+* **Read-After-Write Consistency**: All write requests are forwarded from
+  secondaries to the primary cluster in order to avoid potential conflicts.
+  While replication is near real-time, it is not instantaneous, meaning there
+  is a potential for a client to write to a secondary and a subsequent read to
+  return an old value. Secondaries attempt to mask this from an individual
+  client making subsequent requests by stalling write requests until the write
+  is replicated or a timeout is reached (2 seconds). If the timeout is reached,
+  the client will receive a warning.
+
+* **Stale Reads**: Secondary clusters service reads based on their
+  locally-replicated data. During normal operation updates from a primary are
+  received in near real-time by secondaries. However, during an outage or
+  network service disruption, replication may stall and secondaries may have
+  stale data. The cluster will automatically recover and reconcile any stale
+  data once the outage has recovered, but reads in the intervening period may
+  receive stale data.
+
 [wal]: https://en.wikipedia.org/wiki/Write-ahead_logging
 [merkle]: https://en.wikipedia.org/wiki/Merkle_tree
 [aries]: https://en.wikipedia.org/wiki/Algorithms_for_Recovery_and_Isolation_Exploiting_Semantics