docs: clarify timeout hierarchy in traffic shaping documentation (#8203)

Author: abernix

.changesets/docs_tee_tux_elf_reel.md

@@ -0,0 +1,5 @@
+### Clarify timeout hierarchy for traffic shaping ([PR #8203](https://github.com/apollographql/router/pull/8203))
+
+The documentation reflects more clearly that subgraph timeouts should not be higher than the router timeout or the router timeout will initiate prior to the subgraph.
+
+By [@abernix](https://github.com/abernix) in https://github.com/apollographql/router/pull/8203

docs/source/routing/performance/traffic-shaping.mdx

@@ -66,7 +66,7 @@ The router applies a default timeout of 30 seconds for all requests, including t
 
 #### Router timeouts
 
-You can change the default timeout for client requests to the router like so:
+Configure timeout values for client requests to the router:
 
 ```yaml title="router.yaml"
 traffic_shaping:
@@ -77,16 +77,38 @@ traffic_shaping:
 If the router-level timeout is hit, the router returns a [HTTP 504 status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/504) to indicate a gateway timeout.
 
 #### Subgraph timeouts
-You can change the default timeout for all requests between the router and subgraphs like so:
+
+Configure timeout values for requests between the router and subgraphs:
 
 ```yaml title="router.yaml"
 traffic_shaping:
   all:
     timeout: 50s # If subgraph requests take more than 50 seconds, cancel the request (30 seconds by default)
 ```
 
+Subgraph timeouts apply to each individual subgraph fetch request. There can be multiple subgraph requests, even to the same subgraph, within a single router request.
+
 If the subgraph-level timeout is hit, the router returns a [GraphQL-compliant HTTP 200 status code](https://graphql.github.io/graphql-over-http/). Because the router can handle multiple subgraph requests for one operation, the timeout of one subgraph doesn't immediately invalidate other requests in the query plan. Returning a 200 status code enables the router to return partial data from other requests that didn't timeout.
 
+#### Timeout hierarchy
+
+Set your router timeout to be greater than your subgraph timeouts. This difference provides a processing buffer, which enables the router to properly handle subgraph timeouts and return appropriate error responses to clients.
+
+A properly configured timeout hierarchy:
+
+```yaml title="router.yaml"
+traffic_shaping:
+  router:
+    timeout: 60s # Router: 60 seconds
+  all:
+    timeout: 30s # Default for any subgraphs not explicitly named below
+  subgraphs:
+    products:
+      timeout: 45s # Products subgraph: 45 seconds (lower than router)
+    inventory:
+      timeout: 20s # Inventory subgraph: 20 seconds
+```
+
 <Note>
 
 Since [deferred](/router/executing-operations/defer-support/#what-is-defer) fragments are separate requests, each fragment's request is individually subject to timeouts.