Mention "connecting to streams" blog post in documentation

Author: acogoluegnes

src/docs/asciidoc/api.adoc

@@ -68,6 +68,15 @@ include::{test-examples}/EnvironmentUsage.java[tag=environment-creation-with-uri
 By specifying several URIs, the environment will try to connect to the first one, and
 will pick a new URI randomly in case of disconnection.
 
+[[understanding-connection-logic]]
+===== Understanding Connection Logic
+
+Creating the environment to connect to a cluster node works usually seamlessly.
+Creating publishers and consumers can cause problems as the client uses hints from the cluster to locate the nodes where stream leaders and replicas are located to connect to the appropriate nodes.
+
+These connection hints can be accurate or less appropriate depending on the infrastructure.
+If you hit some connection problems at some point – like hostnames impossible to resolve for client applications - this https://blog.rabbitmq.com/posts/2021/07/connecting-to-streams/[blog post] should help you understand what is going on and fix the issues.
+
 ===== Enabling TLS
 
 TLS can be enabled by using the `rabbitmq-stream+tls` scheme in the URI.

src/docs/asciidoc/overview.adoc

@@ -66,9 +66,7 @@ can also be useful for development and testing.
 * _avoid publishing duplicate messages_ thanks to message de-duplication.
 * _consume asynchronously from streams and resume where left off_ thanks to
 automatic or manual offset tracking.
-* _use cluster nodes appropriately_ by letting the client decide which node to connect to - to
-stream leaders for publishers to minimize inter-node traffic and to stream replicas
-for consumers to offload leaders.
+* _enforce https://blog.rabbitmq.com/posts/2021/07/connecting-to-streams/[best practices] to create client connections_ – to stream leaders for publishers to minimize inter-node traffic and to stream replicas for consumers to offload leaders.
 * _optimize resources_ thanks to automatic growing and shrinking of
 connections depending on the number of publishers and consumers.
 * _let the client handle network failure_ thanks to automatic connection
@@ -99,5 +97,3 @@ The client contains 2 sets of programming interfaces whose stability are of inte
 * Application Programming Interfaces (API): those are the ones used to write application logic. They include the interfaces and classes in the `com.rabbitmq.stream` package (e.g. `Producer`, `Consumer`, `Message`). These API constitute the main programming model of the client and will be kept as stable as possible.
 * Service Provider Interfaces (SPI): those are interfaces to implement mainly technical behavior in the client. They are not meant to be used to implement application logic. Application developers may have to refer to them in the configuration phase and if they want to custom some internal behavior in the client. SPI include interfaces and classes in the `com.rabbitmq.stream.codec`, `com.rabbitmq.stream.compression`, `com.rabbitmq.stream.metrics` packages, among others. _These SPI are susceptible to change, but this should not impact the majority of applications_, as the changes would typically stay intern to the client.
 
-
-

src/docs/asciidoc/performance-tool.adoc

@@ -181,6 +181,8 @@ java -jar stream-perf-test.jar \
 Note the performance tool will automatically configure the client to trust all
 server certificates and to not use a private key (for client authentication).
 
+Have a look at the <<api.adoc#understanding-connection-logic,connection logic section>> in case of connection problem.
+
 ===== Publishing Rate
 
 It is possible to limit the publishing rate with the `--rate` option: