Add a wait for ready user guide as part of 2023Q2 Doc Fixit (#1134)

Fixes b/275390889

content/en/docs/guides/wait-for-ready.md

@@ -0,0 +1,107 @@
+---
+title: Wait-for-Ready
+description: >-
+  Explains how to configure RPCs to wait for the server to be ready before sending the request.
+---
+
+### Overview
+
+This is a feature which can be used on a stub which will cause the RPCs to wait
+for the server to become available before sending the request.  This allows
+for robust batch workflows since transient server problems won't cause failures.
+The deadline still applies, so the wait will be interrupted if the deadline is
+passed.
+
+When an RPC is created when the channel has failed to connect to the server,
+without Wait-for-Ready it will immediately return a failure; with Wait-for-Ready
+it will simply be queued until the connection becomes ready.  The default is
+**without** Wait-for-Ready.
+
+For detailed semantics see [this][grpc doc].
+
+### How to use Wait-for-Ready
+
+You can specify for a stub whether or not it should use Wait-for-Ready, which
+will automatically be passed along when an RPC is created.
+
+{{% alert title="Note" color="info" %}}
+ The RPC can still fail for other reasons besides the server not being
+ready, so error handling is still necessary.
+{{% /alert %}}
+
+The following shows the sequence of events that occur, when a client sends a
+message to a server, based upon channel state and whether or not Wait-for-Ready
+is set.
+```mermaid
+sequenceDiagram
+participant A as Application
+participant RPC
+participant CH as Channel
+participant S as Server 
+A->>RPC: Create RPC using stub
+RPC->>CH: Initiate Communication
+alt channel state: READY
+  CH->>S: Send message
+else Channel state: IDLE or CONNECTING
+  CH-->>CH: Wait for state change
+else Channel state: TRANSIENT_FAILURE
+  alt with Wait-for-Ready
+    CH-->>CH: Wait for channel<br>becoming READY<br>(or a permanent failure)
+    CH->>S: Send message
+  else without Wait-for-Ready
+    CH->>A: Failure
+  end
+else Channel state is a Permanent Failure
+    CH->>A: Failure
+end
+```
+The following is a state based view
+```mermaid
+stateDiagram-v2
+   state "Initiating Communication" as IC
+   state "Channel State" as CS
+   IC-->CS: Check Channel State
+   state CS {
+      state "Permanent Failure" as PF
+      state "TRANSIENT_FAILURE" as TF
+      IDLE --> CONNECTING
+      CONNECTING --> READY
+      READY-->[*]
+      CONNECTING-->TF
+      CONNECTING-->PF
+      TF-->READY
+      TF -->[*]: without\n wait-for-ready
+      TF-->PF
+      PF-->[*]
+   }
+  state "MSG sent" as MS
+  state "RPC Failed" as RF
+  CS-->WAIT:From IDLE /\nCONNECTING
+  CS-->WAIT:From Transient\nFailure with\nWait-for-Ready
+  WAIT-->CS:State Change 
+  CS-->MS: From READY
+  CS-->RF: From Permanent failure or\nTransient Failure without\nWait-for-Ready
+  MS-->[*]
+  RF-->[*]
+```
+
+### Alternatives
+
+- Loop (with exponential backoff) until the RPC stops returning transient failures.
+  - This could be combined, for efficiency, with implementing an `onReady` Handler
+  _(for languages that support this)_.
+- Accept failures that might have been avoided by waiting because you want to
+  fail fast  
+
+### Language Support
+
+| Language | Example           |
+|----------|-------------------|
+| Java     | [Java example]    |
+| Go       | [Go example]      |
+| Python   | [Python example]  |
+
+[Java example]: https://github.com/grpc/grpc-java/blob/master/examples/src/main/java/io/grpc/examples/waitforready/WaitForReadyClient.java
+[Go example]: https://github.com/grpc/grpc-go/tree/master/examples/features/name_resolving
+[Python example]: https://github.com/grpc/grpc/tree/master/examples/python/wait_for_ready
+[grpc doc]: https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md