[DOCS] Reorganizes Introduction and Installation chapters (#1315)

docs/authentication.asciidoc

@@ -5,6 +5,7 @@ This document contains code snippets to show you how to connect to various {es}
 providers.
 
 
+[discrete]
 === Elastic Cloud
 
 If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers 
@@ -38,6 +39,7 @@ const client = new Client({
 ----
 
 
+[discrete]
 === Basic authentication
 
 You can provide your credentials by passing the `username` and `password` 
@@ -69,6 +71,7 @@ const client = new Client({
 ----
 
 
+[discrete]
 === ApiKey authentication
 
 You can use the 
@@ -106,6 +109,7 @@ const client = new Client({
 ----
 
 
+[discrete]
 === SSL configuration
 
 Without any additional configuration you can specify `https://` node urls, and 

docs/breaking-changes.asciidoc

@@ -6,6 +6,7 @@ to install with `npm install elasticsearch` – you will encounter some breaking
 changes.
 
 
+[discrete]
 === Don’t panic!
 
 Every breaking change was carefully weighed, and each is justified. Furthermore, 
@@ -13,6 +14,7 @@ the new codebase has been rewritten with modern JavaScript and has been
 carefully designed to be easy to maintain.
 
 
+[discrete]
 === Breaking changes
 
 *  Minimum supported version of Node.js is `v8`.
@@ -209,6 +211,7 @@ client.transport.request({
 })
 ----
 
+[discrete]
 === Talk is cheap. Show me the code.
 
 You can find a code snippet with the old client below followed by the same code 

docs/configuration.asciidoc

@@ -17,7 +17,7 @@ const client = new Client({
 })
 ----
 
-
+[discrete]
 === Basic options
 
 [cols=2*]
@@ -242,6 +242,7 @@ const client = new Client({
 |===
 
 
+[discrete]
 === Advanced configuration
 
 If you need to customize the client behavior heavily, you are in the right 
@@ -253,6 +254,7 @@ place! The client allows you to customize the following internals:
 * `Serializer` class
 
 
+[discrete]
 === `Transport`
 
 This class is responsible for performing the request to {es} and handling 
@@ -287,6 +289,7 @@ class MyTransport extends Transport {
 ----
 
 
+[discrete]
 === `ConnectionPool`
 
 This class is responsible for keeping in memory all the {es} Connection that we 
@@ -310,6 +313,7 @@ const client = new Client({
 ----
 
 
+[discrete]
 === `Connection`
 
 This class represents a single node, it holds every information we have on the 
@@ -333,6 +337,7 @@ const client = new Client({
 ----
 
 
+[discrete]
 === `Serializer`
 
 This class is responsible for the serialization of every request, it offers the 

docs/helpers.asciidoc

@@ -6,12 +6,16 @@ The client comes with an handy collection of helpers to give you a more comforta
 CAUTION: The client helpers are experimental, and the API may change in the next minor releases.
 The helpers will not work in any Node.js version lower than 10.
 
+
+[discrete]
 === Bulk Helper
 
 ~Added~ ~in~ ~`v7.7.0`~
 
 Running Bulk requests can be complex due to the shape of the API, this helper aims to provide a nicer developer experience around the Bulk API.
 
+
+[discrete]
 ==== Usage
 [source,js]
 ----
@@ -150,8 +154,12 @@ const b = client.helpers.bulk({
 
 |===
 
+
+[discrete]
 ==== Supported operations
 
+
+[discrete]
 ===== Index
 [source,js]
 ----
@@ -165,6 +173,8 @@ client.helpers.bulk({
 })
 ----
 
+
+[discrete]
 ===== Create
 [source,js]
 ----
@@ -178,7 +188,10 @@ client.helpers.bulk({
 })
 ----
 
+
+[discrete]
 ===== Update
+
 [source,js]
 ----
 client.helpers.bulk({
@@ -195,7 +208,10 @@ client.helpers.bulk({
 })
 ----
 
+
+[discrete]
 ===== Delete
+
 [source,js]
 ----
 client.helpers.bulk({
@@ -208,7 +224,10 @@ client.helpers.bulk({
 })
 ----
 
+
+[discrete]
 ==== Abort a bulk operation
+
 If needed, you can abort a bulk operation at any time. The bulk helper returns a https://promisesaplus.com/[thenable], which has an `abort` method.
 
 NOTE: The abort method will stop the execution of the bulk operation, but if you are using a concurrency higher than one, the operations that are already running will not be stopped.
@@ -235,7 +254,10 @@ const b = client.helpers.bulk({
 console.log(await b)
 ----
 
+
+[discrete]
 ==== Passing custom options to the Bulk API
+
 You can pass any option supported by the link:{ref}/docs-bulk.html#docs-bulk-api-query-params[Bulk API] to the helper, and the helper will use those options in conjuction with the Bulk 
 API call.
 
@@ -252,6 +274,8 @@ const result = await client.helpers.bulk({
 })
 ----
 
+
+[discrete]
 ==== Usage with an async generator
 
 [source,js]
@@ -282,6 +306,8 @@ const result = await client.helpers.bulk({
 console.log(result)
 ----
 
+
+[discrete]
 === Multi Search Helper
 
 ~Added~ ~in~ ~`v7.8.0`~
@@ -290,7 +316,10 @@ If you are sending search request at a high rate, this helper might be useful fo
 It will use the mutli search API under the hood to batch the requests and improve the overall performances of your application. +
 The `result` exposes a `documents` property as well, which allows you to access directly the hits sources.
 
+
+[discrete]
 ==== Usage
+
 [source,js]
 ----
 const { Client } = require('@elastic/elasticsearch')
@@ -372,7 +401,10 @@ const m = client.helpers.msearch({
 
 |===
 
+
+[discrete]
 ==== Stopping the Msearch Helper
+
 If needed, you can stop a msearch processor at any time. The msearch helper returns a https://promisesaplus.com/[thenable], which has an `stop` method.
 
 If you are creating multiple msearch helpers instances and using them for a limitied period of time, remember to always use the  `stop` method once you have finished using them, otherwise your application will start leaking memory.
@@ -405,6 +437,8 @@ m.search(
 setImmediate(() => m.stop())
 ----
 
+
+[discrete]
 === Search Helper
 
 ~Added~ ~in~ ~`v7.7.0`~
@@ -430,6 +464,8 @@ for (const doc of documents) {
 }
 ----
 
+
+[discrete]
 === Scroll Search Helper
 
 ~Added~ ~in~ ~`v7.7.0`~
@@ -455,6 +491,8 @@ for await (const result of scrollSearch) {
 }
 ----
 
+
+[discrete]
 ==== Clear a scroll search
 
 If needed, you can clear a scroll search by calling `result.clear()`:
@@ -468,6 +506,8 @@ for await (const result of scrollSearch) {
 }
 ----
 
+
+[discrete]
 ==== Quickly getting the documents
 
 If you only need the documents from the result of a scroll search, you can access them via `result.documents`:
@@ -479,6 +519,8 @@ for await (const result of scrollSearch) {
 }
 ----
 
+
+[discrete]
 === Scroll Documents Helper
 
 ~Added~ ~in~ ~`v7.7.0`~

docs/index.asciidoc

@@ -4,6 +4,7 @@
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
 include::introduction.asciidoc[]
+include::installation.asciidoc[]
 include::usage.asciidoc[]
 include::configuration.asciidoc[]
 include::reference.asciidoc[]

docs/installation.asciidoc

@@ -0,0 +1,21 @@
+[[installation]]
+== Installation
+
+This page guides you through the installation process of the client.
+
+To install the latest version of the client, run the following command:
+
+[source,sh]
+----
+npm install @elastic/elasticsearch
+----
+
+To install a specific major version of the client, run the following command:
+
+[source,sh]
+----
+npm install @elastic/elasticsearch@<major>
+----
+
+To learn more about the supported major versions, please refer to the 
+<<js-compatibility-matrix>>.

docs/introduction.asciidoc

@@ -1,9 +1,11 @@
 [[introduction]]
 == Introduction
 
-The official Node.js client for {es}.
+This is the official Node.js client for {es}. This page gives a quick overview 
+about the features of the client.
 
 
+[discrete]
 === Features
 
 * One-to-one mapping with REST API.
@@ -15,15 +17,9 @@ The official Node.js client for {es}.
 * TypeScript support out of the box.
 
 
-=== Install
+[discrete]
-
+[[js-compatibility-matrix]]
-[source,sh]
+=== Compatibility matrix
-----
-npm install @elastic/elasticsearch
-----
-
-
-=== Compatibility
 
 The minimum supported version of Node.js is `v8`.
 
@@ -50,13 +46,8 @@ using.
 |`5.x`
 |===
 
-To install a specific major version of the client, run the following command:
-
-----
-npm install @elastic/elasticsearch@<major>
-----
-
 
+[discrete]
 ==== Browser
 
 WARNING: There is no official support for the browser environment. It exposes
@@ -64,6 +55,7 @@ your {es} instance to everyone, which could lead to security issues. We
 recommend you to write a lightweight proxy that uses this client instead.
 
 
+[discrete]
 === Quick start
 
 First of all, require, then initialize the client:
@@ -176,7 +168,7 @@ async function run () {
 run().catch(console.log)
 ----
 
-
+[discrete]
 ==== Install multiple versions
 
 If you are using multiple versions of {es}, you need to use multiple versions of

docs/observability.asciidoc

@@ -11,6 +11,8 @@ a large codebase with many events happening at the same time.
 To help you with this, the client offers you a correlation id system and other 
 features. Let's see them in action.
 
+
+[discrete]
 === Events
 
 The client is an event emitter, this means that you can listen for its event and 
@@ -126,6 +128,7 @@ request: {
 ----
 
 
+[discrete]
 === Correlation id
 
 Correlating events can be quite hard, especially if there are many events at the 
@@ -193,6 +196,7 @@ client.search({
 ----
 
 
+[discrete]
 === Context object
 
 Sometimes, you might need to make some custom data available in your events, you 
@@ -268,6 +272,7 @@ client.search({
 ----
 
 
+[discrete]
 === Client name
 
 If you are using multiple instances of the client or if you are using multiple 
@@ -321,6 +326,7 @@ child.search({
 ----
 
 
+[discrete]
 === X-Opaque-Id support
 
 To improve the overall observability, the client offers an easy way to configure 

docs/testing.asciidoc

@@ -33,6 +33,8 @@ the `Connection` component since it has very few responsibilities and
 it does not interact with other internal components other than getting
 requests and returning responses.
 
+
+[discrete]
 === `@elastic/elasticsearch-mock`
 
 Writing each time a mock for your test can be annoying and error-prone,

docs/typescript.asciidoc

@@ -1,5 +1,4 @@
 [[typescript]]
-
 == TypeScript support
 
 The client offers a first-class support for TypeScript, since it ships the type 
@@ -39,6 +38,7 @@ console.log(response.body)
 You don't have to specify all the generics, but the order must be respected.
 
 
+[discrete]
 === A complete example
 
 [source,ts]

docs/usage.asciidoc

@@ -81,6 +81,7 @@ client.search({
 ----
 
 
+[discrete]
 === Aborting a request
 
 If needed, you can abort a running request by calling the `request.abort()` method returned by the API.
@@ -134,6 +135,7 @@ request.abort()
 ----
 
 
+[discrete]
 === Request specific options
 If needed you can pass request specific options in a second object:
 
@@ -210,6 +212,8 @@ _Default:_ `null`
 _Default:_ `null`
 |===
 
+
+[discrete]
 === Connecting through a proxy
 
 ~Added~ ~in~ ~`v7.10.0`~
@@ -250,6 +254,8 @@ const client = new Client({
 })
 ----
 
+
+[discrete]
 === Error handling
 
 The client exposes a variety of error objects that you can use to enhance your