From 07ec527ea52e179096f5cddf035b8a4d3b33037e Mon Sep 17 00:00:00 2001
From: Purnesh Dixit <purneshdixit@google.com>
Date: Fri, 13 Dec 2024 00:58:12 +0530
Subject: [PATCH] address doug's comments

---
 .../en/docs/guides/server-graceful-stop.md    | 29 +++++++------------
 1 file changed, 11 insertions(+), 18 deletions(-)

diff --git a/content/en/docs/guides/server-graceful-stop.md b/content/en/docs/guides/server-graceful-stop.md
index 3cc9ad74d6..3b360f6014 100644
--- a/content/en/docs/guides/server-graceful-stop.md
+++ b/content/en/docs/guides/server-graceful-stop.md
@@ -1,5 +1,5 @@
 ---
-title: Gracefully stopping a server
+title: Gracefull Shutdown
 description: >-
   Explains how to gracefully stop/shutdown a gRPC server.
 ---
@@ -17,6 +17,9 @@ accepting new RPCs. In-flight RPCs are allowed to continue until they complete
 or a specified deadline is reached. Once all active RPCs finish or the deadline
 expires, the server shuts down completely.
 
+While a graceful shutdown is optional, it's highly recommended. You can
+shutdown without a graceful shutdown first but that would not be recommended.
+
 ### How to do Graceful Server Shutdown
 
 The exact implementation of the "Graceful shutdown function" varies depending on
@@ -24,7 +27,7 @@ the programming language you are using. However, the general pattern
 involves:
 
 - Initiating the graceful shutdown process by calling "Graceful shutdown
-  Function" on your gRPC server object. This function blocks until all
+  function" on your gRPC server object. This function blocks until all
   currently running RPCs complete. This ensures that in-flight requests are
   allowed to finish processing.
 - Specify a timeout period to limit the time allowed for in-progress RPCs to
@@ -43,39 +46,29 @@ shutdown.
 sequenceDiagram
 Client->>Server: New RPC Request 1
 Client->>Server: New RPC Request 2
-Server->>Client: Processing RPC 1
-Server->>Client: Processing RPC 2
-Server-->>Server: Graceful Stop Invoked
+Server-->>Server: Graceful Shutdown Invoked
 Server->>Client: Continues Processing In-Flight RPCs
-Client->>Server: New RPC Request 3 (Rejected)
+Client->>Client: Detects server shutdown and go find other servers if available 
 alt RPCs complete within timeout
     Server->>Client: Completes RPC 1
     Server->>Client: Completes RPC 2
-    Server-->>Server: Shutdown Complete
-    Client->>Server: New RPC Request 4 (Rejected)
+    Server-->>Server: Graceful Shutdown Complete
 else Timeout reached
-    Server->>Client: RPC 2 and other pending RPCs forcefully terminated
-    Server-->>Server: Shutdown Complete
-    Client->>Server: New RPC Request 4 (Rejected)
+    Server->>Client: Forceful Shutdown Invoked, terminating pending RPCs
+    Server-->>Server: Forceful Shutdown Complete
 end
 ```
 The following is a state based view
 ```mermaid
 stateDiagram-v2
     [*] --> RUNNING : Server Started
-    RUNNING --> GRACEFUL_STOP_INITIATED : GracefulStop() Called (with Timeout)
+    RUNNING --> GRACEFUL_STOP_INITIATED : Graceful Stop Called (with Timeout)
     GRACEFUL_STOP_INITIATED --> GRACEFUL_STOPPING : Reject New RPCs
     GRACEFUL_STOPPING --> TERMINATED : Complete In-Flight RPCs (Before Timeout)
     GRACEFUL_STOPPING --> FORCE_STOP : Timeout Reached
     FORCE_STOP --> TERMINATED : Force Terminate Pending RPCs and Shutdown
 ```
 
-### Alternatives
-
-- Forceful Shutdown: Immediately terminates the server using "Forceful Shutdown
-  Function" on server object, potentially interrupting active RPCs and leading
-  to errors on the client-side. Use only as a last resort.
-
 ### Language Support
 
 | Language | Example           |