Add doc about timeout best practices

docs/configuration.asciidoc

@@ -2,10 +2,11 @@
 == Configuration
 
 
-The client is designed to be easily configured for your needs. In the following 
+The client is designed to be easily configured for your needs. In the following
 section, you can see the possible options that you can use to configure it.
 
 * <<basic-config>>
 * <<advanced-config>>
+* <<timeout-best-practices>>
 * <<child>>
 * <<client-testing>>

docs/index.asciidoc

@@ -21,3 +21,4 @@ include::reference.asciidoc[]
 include::examples/index.asciidoc[]
 include::helpers.asciidoc[]
 include::redirects.asciidoc[]
+include::timeout-best-practices.asciidoc[]

docs/timeout-best-practices.asciidoc

@@ -0,0 +1,10 @@
+[[timeout-best-practices]]
+=== Timeout best practices
+
+This client is configured by default to operate like many HTTP client libraries do, by using a relatively short (30 second) timeout on all requests sent to {es}, raising a `TimeoutError` when that time period has elapsed without receiving a response. However, {es} will always eventually respond to any request, even if it takes several minutes. The {ref}/modules-network.html#_http_client_configuration[official {es} recommendation] is to disable response timeouts entirely by default.
+
+Since changing this default would be a breaking change, we won't do that until the next major release. In the meantime, here is our recommendation for properly configuring your client:
+
+* Ensure keep-alive is enabled; this is the default, so no settings need to be changed, unless you have set `agent` to `false` or provided an alternate `agent` that disables keep-alive
+* If using the default `UndiciConnection`, disable request timeouts by setting `timeout` to `0`
+* If using the legacy `HttpConnection`, set `timeout` to a very large number (e.g. `86400000`, or one day)