[DOCS] Add usage section and recommendations (#6973) (#6980)

* Add usage sub-section and move examples

* Reorder items

* Stub out sections and fix headings

* Add additional dependency

* Reorder includes

* Update to ref-current for docs links

* Add initial recommendations

* Update recommendations

* Attempt to fix generated URLs

* Update includes

* Fix connecting link

Co-authored-by: Steve Gordon <[email protected]>

Author: github-actions[bot]

docs/connecting.asciidoc

@@ -112,7 +112,8 @@ SHA256 Fingerprint=<FINGERPRINT>
 ----
 
 Visit the 
-{ref-current}/configuring-stack-security.html[Connect clients to {es}] documentation for more information.
+{ref}/configuring-stack-security.html[Start the Elastic Stack with security enabled automatically] 
+documentation for more information.
 
 The following snippet shows you how to create a client instance that connects to 
 your {es} cluster via a single node, using the CA fingerprint:

docs/index.asciidoc

@@ -1,14 +1,11 @@
-:title-separator: |
-
 [[elasticsearch-net-reference]]
 = Elasticsearch .NET Client
 
-:net-client: Elasticsearch .NET Client
-:ref-current: {ref}
-
-
+include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[]
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
+:net-client: Elasticsearch .NET Client
+
 include::intro.asciidoc[]
 
 include::install.asciidoc[]
@@ -17,7 +14,7 @@ include::connecting.asciidoc[]
 
 include::configuration.asciidoc[]
 
-include::examples.asciidoc[]
+include::usage/index.asciidoc[]
 
 include::troubleshooting.asciidoc[]
 

docs/examples.asciidoc renamed to docs/usage/examples.asciidoc

@@ -1,11 +1,11 @@
 [[examples]]
-== Examples
+=== CRUD usage examples
 
 This page helps you to understand how to perform various basic {es} CRUD 
-operations using the .NET client. It demonstrates how to create a document by 
-indexing an object into {es}, read a document back, retrieving it by ID or 
-performing a search, update one of the fields in a document and delete a 
-specific document.
+(create, read, update, delete) operations using the .NET client. It demonstrates 
+how to create a document by indexing an object into {es}, read a document back,
+retrieving it by ID or performing a search, update one of the fields in a 
+document and delete a specific document.
 
 These examples assume you have an instance of the `ElasticsearchClient` 
 accessible via a local variable named `client` and several using directives in 
@@ -45,7 +45,7 @@ using the ID specified by the value of this property.
 
 [discrete]
 [[indexing-net]]
-=== Indexing a document
+==== Indexing a document
 
 Documents can be indexed by creating an instance representing a tweet and 
 indexing it via the client. In these examples, we will work with an index named 
@@ -77,7 +77,7 @@ operation succeeded.
 
 [discrete]
 [[getting-net]]
-=== Getting a document
+==== Getting a document
 
 [source,csharp]
 ----
@@ -91,7 +91,7 @@ accessible on the response via the `Source` property.
 
 [discrete]
 [[searching-net]]
-=== Searching for documents
+==== Searching for documents
 
 The client exposes a fluent interface and a powerful query DSL for searching.
 
@@ -146,7 +146,7 @@ search operation.
 
 [discrete]
 [[updating-net]]
-=== Updating documents
+==== Updating documents
 
 Documents can be updated in several ways, including by providing a complete 
 replacement for an existing document ID.
@@ -169,7 +169,7 @@ if (response.IsValid)
 
 [discrete]
 [[deleting-net]]
-=== Deleting documents
+==== Deleting documents
 
 Documents can be deleted by providing the ID of the document to remove.
 

docs/usage/index.asciidoc

@@ -0,0 +1,16 @@
+[[usage]]
+== Using the .NET Client
+
+The sections below provide tutorials on the most frequently used and some less obvious features of {es}.
+
+For a full reference, see the {ref}/[Elasticsearch documentation] and in particular the {ref}/rest-apis.html[REST APIs] section. The {net-client} follows closely the JSON structures described there.
+
+If you're new to {es}, make sure also to read {ref}/getting-started.html[Elasticsearch's quick start] that provides a good introduction.
+
+* <<recommendations, Usage recommendations>>
+* <<examples, CRUD usage examples>>
+
+NOTE: This is still a work in progress, more sections will be added in the near future.
+
+include::recommendations.asciidoc[]
+include::examples.asciidoc[]

docs/usage/recommendations.asciidoc

@@ -0,0 +1,37 @@
+[[recommendations]]
+=== Usage recommendations
+
+To achieve the most efficient use of the {net-client}, we recommend following 
+the guidance defined in this article.
+
+[discrete]
+==== Reuse the same client instance
+
+When working with the {net-client} we recommend that consumers reuse a single 
+instance of `ElasticsearchClient` for the entire lifetime of the application. 
+When reusing the same instance:
+
+- initialization overhead is limited to the first usage. 
+- resources such as TCP connections can be pooled and reused to improve 
+efficiency.
+- serialization overhead is reduced, improving performance. 
+
+The `ElasticsearchClient` type is thread-safe and can be shared and reused 
+across multiple threads in consuming applications. Client reuse can be achieved 
+by creating a singleton static instance or by registering the type with a 
+singleton lifetime when using dependency injection containers.
+
+[discrete]
+==== Prefer asynchronous methods
+
+The {net-client} exposes synchronous and asynchronous methods on the 
+`ElasticsearchClient`. We recommend always preferring the asynchronous methods, 
+which have the `Async` suffix. Using the {net-client} requires sending HTTP 
+requests to {es} servers. Access to {es} is sometimes slow or delayed, and some 
+complex queries may take several seconds to return. If such operations are 
+blocked by calling the synchronous methods, the thread must wait until the HTTP 
+request is complete. In high-load scenarios, this can cause significant thread 
+usage, potentially affecting the throughput and performance of consuming 
+applications. By preferring the asynchronous methods, application threads can 
+continue with other work that doesn't depend on the web resource until the 
+potentially blocking task completes.