Rewrite docs and separate content for a more human readable structure

Signed-off-by: Danil Grigorev <danil.grigorev@suse.com>

docs/getting-started/install_capi_operator.md

@@ -2,30 +2,61 @@
 sidebar_position: 3
 ---
 
-# Install CAPI Operator
+# Install Cluster API Operator
 
 ## Installing CAPI and providers
 
-CAPI and desired CAPI providers could be installed using helm based installation for [`Cluster API Operator`](https://github.com/kubernetes-sigs/cluster-api-operator).
+`CAPI` and desired `CAPI` providers could be installed using helm based installation for [`Cluster API Operator`](https://github.com/kubernetes-sigs/cluster-api-operator).
 
 ### Cluster API operator path
+To install version `1.4.4` of the `CAPI` + `Docker` provider, follow these steps:
 
-For example, to install latest version of CAPI + docker provider, first, the helm repo should be added with:
+1. Add the Helm repository for the `Cluster API Operator` by running the following command:
 ```bash
 helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator
+```
+2. Update the Helm repository by running the following command:
+```bash
 helm repo update
 ```
-and installed together with [cert-manager](https://github.com/cert-manager/cert-manager) using:
+3. Install the `Cluster API Operator` using the following command, which will also install `cert-manager`:
 ```bash
 helm install capi-operator capi-operator/cluster-api-operator
 	--create-namespace -n capi-operator-system
-	--set infrastructure=docker
+	--set infrastructure=docker:v1.4.4
 	--set cert-manager.enabled=true
-	--timeout 90s --wait # core Cluster API with kubeadm bootstrap and control plane providers will also be installed
+	--timeout 90s --wait # Core Cluster API with kubeadm bootstrap and control plane providers will also be installed
 ```
 *Note: `cert-manager` is a hard requirement for CAPI and `Cluster API Operator`*
 
+To provide additional environment variables, choose some feature gates, or provide cloud credentials, similar to `clusterctl` [common provider](https://cluster-api.sigs.k8s.io/user/quick-start#initialization-for-common-providers), in `Cluster API Operator`, a variables secret could be used. A `name` and a `namespace` of the secret could be specified for the `Cluster API Operator`.
+
+```bash
+helm install capi-operator capi-operator/cluster-api-operator
+	--create-namespace -n capi-operator-system
+	--set infrastructure=docker:v1.4.4
+	--set cert-manager.enabled=true
+	--timeout 90s
+	--secret-name <secret_name>
+	--secret-namespace <secret_namespace>
+	--wait
+```
+
+Example secret data:
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: variables
+  namespace: default
+type: Opaque
+stringData:
+  CLUSTER_TOPOLOGY: "true"
+  EXP_CLUSTER_RESOURCE_SET: "true"
+```
+
 For any scenarios when there is a need to provide additional environment variables, to choose some feature gates or provide cloud credentials, similar to `clusterctl` common provider [initialization options](https://cluster-api.sigs.k8s.io/user/quick-start#initialization-for-common-providers), in `Cluster API Operator` a variables secret could be used. A `name` and a `namespace` of the secret could be specified for the `Cluster API Operator`:
+
 ```bash
 helm install capi-operator capi-operator/cluster-api-operator
 	--create-namespace -n capi-operator-system
@@ -50,9 +81,12 @@ stringData:
   EXP_CLUSTER_RESOURCE_SET: "true"
 ```
 
-To select more then one desired providers to be installed together with `Cluster API Operator`, `--infrastructure` flag could be specified with multiple provider names separated by `,`. Also a specific version could be specified like so:
+To select more than one desired provider to be installed together with the `Cluster API Operator`, the `--infrastructure` flag can be specified with multiple provider names separated by a comma. For example:
+
 ```bash
-helm install ... infrastructure=docker:v1.4.4,azure:v1.4.4
+helm install ... infrastructure="docker:v1.4.4;azure:v1.4.4"
 ```
 
-For more fine-grained control on the providers and other components installed with CAPI see the [Add infrastructure provider](../tasks/capi-operator/add_infrastructure_provider.md) section.
+The `infrastructure` flag is set to `docker:v1.4.4;azure:v1.4.4`, representing the desired provider names. This means that the `Cluster API Operator` will install and manage multiple provider systems, `Docker` and `Azure` respectively, with versions `1.4.4` specified.
+
+For more fine-grained control on the providers and other components installed with CAPI, see the [Add infrastructure provider](../tasks/capi-operator/add_infrastructure_provider.md) section.

docs/getting-started/install_turtles_operator.md

@@ -4,15 +4,20 @@ sidebar_position: 4
 
 # Install Rancher Turtles Operator
 
-Rancher turtles requires to have a direct connection to the Rancher Manager cluster. This could be achieved by:
-1. Installing in in the same cluster as the Rancher Manager.
+A `Rancher Turtles` requires a connection to the `Rancher Manager` cluster. This can be achieved by:
+
+1. Installing it in the same cluster as the `Rancher Manager`.
+
+*Note: In future we will support different deployment topologies*
+
+Recommended path of installation for the operator is by using `Helm`. To install it in the cluster, a repository should be added first:
 
-Recommended path of installation for the operator is by using helm. To install it in the cluster a repository should be added first:
 ```bash
 helm repo add turtles https://rancher-sandbox.github.io/rancher-turtles/
 helm repo update
 ```
-and installed into `rancher-turtles-system` namespace with:
+and then it can be installed into the `rancher-turtles-system` namespace with:
+
 ```bash
 helm install rancher-turtles turtles/rancher-turtles
     -n rancher-turtles-system

docs/getting-started/rancher.md

@@ -4,22 +4,25 @@ sidebar_position: 2
 
 # Rancher Setup
 
-## Installing rancher
+## Installing Rancher
 
-In order to install rancher in existing/new k8s cluster, aside from following one of the [official installation guides](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-and-upgrade), rancher should have `embedded-cluster-api` feature disabled. To do so, when installing rancher in the k8s cluster, the following feature flag should be specified with the `helm` command:
+To install `Rancher` in an existing or new Kubernetes cluster, you can use the following steps:
+
+1. First, make sure to follow one of the official [installation guides](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-and-upgrade) for `Rancher`.
+2. When installing `Rancher` using the `helm` command, use the `--set` option to specify the `features` parameter. For the `embedded-cluster-api` feature, set the value to `false` to disable it.
+3. Use the `--version` option to specify the version of `Rancher` you want to install. In this case, use the [recommentded](../getting-started/intro.md#prerequisites) `Rancher` version for `Rancher Turtles`.
+
+Here's the complete command to install `Rancher` with the `embedded-cluster-api` feature disabled. Replace `<rancher-hostname>` with the actual hostname of your `Rancher` server:
 
 ```bash
-helm install rancher rancher-stable/rancher
-	--set features=embedded-cluster-api=false # Disabling embedded CAPI feature
-	--set hostname=<rancher-hostname>
-	--version v2.7.5
-	--namespace cattle-system
-	--create-namespace --wait
+helm install rancher rancher-stable/rancher --set features=embedded-cluster-api=false --set hostname=<rancher-hostname> --set version=<rancher-version> --set namespace=cattle-system --create-namespace --wait
 ```
 
 ## Existing rancher installation
 
-To allow Rancher Turtles to be installed in the existing rancher cluster, `embedded-cluster-api` feature should be created from the manifest first:
+To install `Rancher Turtles` in an existing `Rancher` cluster, follow these steps:
+
+1. Create a `feature.yaml` file, with `embedded-cluster-api` feature disabled:
 ```yaml title="feature.yaml"
 apiVersion: management.cattle.io/v3
 kind: Feature
@@ -28,8 +31,7 @@ metadata:
 spec:
   value: false
 ```
-
-To apply it in the cluster:
+2. Use `kubectl` to apply the `feature.yaml` file to the cluster:
 ```bash
 kubectl apply -f feature.yaml
-```
+```

docs/tasks/capi-operator/add_infrastructure_provider.md

@@ -4,39 +4,7 @@ sidebar_position: 2
 
 # Add Infrastructure Provider
 
-This section describes how an infrastructure provider such as Azure could be added using Cluster API Operator.
-
-## Basic Cluster API Provider Installation
-
-This section describes the basic process of installing Cluster API providers using the operator. The Cluster API operator manages five types of objects:
-
-- CoreProvider
-- BootstrapProvider
-- ControlPlaneProvider
-- InfrastructureProvider
-- AddonProvider
-
-Please note that this example provides a basic configuration of Azure Infrastructure provider for getting started. More detailed examples and CRD descriptions will be provided in subsequent sections of this document.
-
-### Installing the CoreProvider
-
-The first step is to install the CoreProvider, which is responsible for managing the Cluster API CRDs and the Cluster API controller.
-
-Any existing namespace could be utilized for providers in the Kubernetes cluster. However, before creating a provider object, make sure the specified namespace has been created. In the example below, we use the `capi-system` namespace. To create this namespace through either the Command Line Interface (CLI) by running `kubectl create namespace capi-system`, or the declarative approach described in the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/namespaces-walkthrough/#create-new-namespaces) could be used.
-
-*Example:*
-
-```yaml
-apiVersion: operator.cluster.x-k8s.io/v1alpha2
-kind: CoreProvider
-metadata:
-  name: cluster-api
-  namespace: capi-system
-spec:
-  version: v1.4.4
-```
-
-**Note:** Only one CoreProvider can be installed at the same time on a single cluster.
+This section describes how an infrastructure provider such as `Azure` could be added using `Cluster API Operator`.
 
 ### Installing Azure Infrastructure Provider
 

docs/tasks/capi-operator/basic_cluster_api_provider_installation.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+---
+
+# Basic Cluster API Provider Installation
+
+This section describes the basic process of installing `CAPI` providers using the operator. The `Cluster API Operator` manages five types of objects:
+
+- `CoreProvider`
+- `BootstrapProvider`
+- `ControlPlaneProvider`
+- `InfrastructureProvider`
+- `AddonProvider`
+
+Please note that this example provides a basic configuration of Azure Infrastructure provider for getting started. More detailed examples and CRD descriptions are provided in the `Cluster API Operator` [documentation](https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#readme)

docs/tasks/capi-operator/installing_core_provider.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 3
+---
+
+# Installing the CoreProvider
+
+The first step is to install the CoreProvider, which is responsible for managing the Cluster API CRDs and the Cluster API controller.
+
+Any existing namespace could be utilized for providers in the Kubernetes cluster. However, before creating a provider object, make sure the specified namespace has been created. In the example below, we use the `capi-system` namespace. To create this namespace through either the Command Line Interface (CLI) by running `kubectl create namespace capi-system`, or the declarative approach described in the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/namespaces-walkthrough/#create-new-namespaces) could be used.
+
+*Example:*
+
+```yaml
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: CoreProvider
+metadata:
+  name: cluster-api
+  namespace: capi-system
+spec:
+  version: v1.4.4
+```
+
+**Note:** Only one CoreProvider can be installed at the same time on a single cluster.