Fix class name; edit for clarity, progressive structure

Author: marciw

docs/reference/transport/rest5-client/config/basic_authentication.md

@@ -1,7 +1,7 @@
 
 # Basic authentication
 
-Configuring basic authentication can be done by providing an `HttpClientConfigCallback` while building the `RestClient` through its builder. The interface has one method that receives an instance of [`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`](https://hc.apache.org/httpcomponents-asyncclient-4.1.x/current/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html) as an argument and has the same return type. The http client builder can be modified and then returned. In the following example we set a default credentials provider that requires basic authentication.
+To use basic authentication in the REST 5 client, set a default authorization header:
 
 % :::{include-code} src={{doc-tests-src}}/rest5_client/RestClientDocumentation.java tag=rest-client-config-basic-auth
 ```java
@@ -16,7 +16,9 @@ Rest5ClientBuilder restClient = Rest5Client
 
 ```
 
-Preemptive Authentication can be disabled, which means that every request will be sent without authorization headers to see if it is accepted and, upon receiving an HTTP 401 response, it will resend the exact same request with the basic authentication header. If you wish to do this, then you can do so by disabling it via the `HttpClientConfigCallback`:
+To configure authentication behavior, pass an `HttpClientConfigCallback` when building the `Rest5Client`. The callback's single method takes an instance of [`org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder`](https://hc.apache.org/httpcomponents-client-5.5.x/current/httpclient5/apidocs/org/apache/hc/client5/http/impl/async/HttpAsyncClientBuilder.html) as an argument and returns the same type, so you can modify the provided builder and return it for the client to use.
+
+By default, the HTTP client uses preemptive authentication: it includes credentials in the initial request. You might want to use non-preemptive authentication, which sends a request without credentials and retries with the header after a `401 Unauthorized` challenge. To do this, set an `HttpClientConfigCallback` with auth caching disabled:
 
 % :::{include-code} src={{doc-tests-src}}/rest5_client/RestClientDocumentation.java tag=rest-client-config-disable-preemptive-auth
 ```java
@@ -26,12 +28,12 @@ var creds = Base64.getEncoder().encodeToString("user:test-user-password".getByte
 
 Rest5ClientBuilder restClient = Rest5Client
     .builder(new HttpHost("https", "localhost", 9200))
-    .setHttpClientConfigCallback(HttpAsyncClientBuilder::disableAuthCaching)
+    .setHttpClientConfigCallback(HttpAsyncClientBuilder::disableAuthCaching) <1>
     .setDefaultHeaders(new Header[]{
         new BasicHeader("Authorization", "Basic " + creds)
     });
 ```
 
-1. Disable preemptive authentication
-
+1. Disables preemptive authentication
 
+For more options, refer to [](other_authentication_methods.md).