address more comments

Author: fabriziopandini

docs/book/src/SUMMARY.md

@@ -8,17 +8,17 @@
     - [Certificate Management](./tasks/certs/index.md)
         - [Using Custom Certificates](./tasks/certs/using-custom-certificates.md)
         - [Generating a Kubeconfig](./tasks/certs/generate-kubeconfig.md)
-- [clusterctl CLI](./clusterctl/intro.md)
-    - [clusterctl Commands](./clusterctl/commands.md)
-        - [init](./clusterctl/init.md)
-        - [config cluster](clusterctl/config-cluster.md)
-        - [move](./clusterctl/move.md)
-        - [adopt](clusterctl/adopt.md)
-        - [upgrade](./clusterctl/upgrade.md)
-        - [delete](clusterctl/delete.md)
-    - [clusterctl Configuration](clusterctl/configuring-clusterctl.md)
-    - [clusterctl Provider Contract](clusterctl/contract.md)
-    - [clusterctl for Developers](clusterctl/dev.md)
+- [clusterctl CLI](./clusterctl/overview.md)
+    - [clusterctl Commands](clusterctl/commands/commands.md)
+        - [init](clusterctl/commands/init.md)
+        - [config cluster](clusterctl/commands/config-cluster.md)
+        - [move](./clusterctl/commands/move.md)
+        - [adopt](clusterctl/commands/adopt.md)
+        - [upgrade](clusterctl/commands/upgrade.md)
+        - [delete](clusterctl/commands/delete.md)
+    - [clusterctl Configuration](clusterctl/configuration.md)
+    - [clusterctl Provider Contract](clusterctl/provider-contract.md)
+    - [clusterctl for Developers](clusterctl/developers.md)
 - [Developer Guide](./architecture/developer-guide.md)
     - [Repository Layout](./architecture/repository-layout.md)
     - [Rapid iterative development with Tilt](./developer/tilt.md)

docs/book/src/clusterctl/command-init.md

@@ -0,0 +1 @@
+# init

docs/book/src/clusterctl/adopt.md renamed to docs/book/src/clusterctl/commands/adopt.md

@@ -17,7 +17,7 @@ The `clusterctl init` command accepts in input a list of providers to install.
 You can use the `clusterctl config providers` command to get the list of supported providers.
 
 If the provider of your choice is missing, you can customize the list of supported providers by using the
-[clusterctl configuration](configuring-clusterctl.md) file. 
+[clusterctl configuration](../configuration.md) file. 
 
 </aside>
 
@@ -171,7 +171,7 @@ To access provider specific information, such as the components YAML to be used
 `clusterctl init` accesses the **provider repositories**, that are well-known places where the release assets for 
 a provider are published.
 
-See [clusterctl configuration](configuring-clusterctl.md) for more info about provider repository configurations.
+See [clusterctl configuration](../configuration.md) for more info about provider repository configurations.
 
 <aside class="note">
 
@@ -186,7 +186,7 @@ the user is required to save the file under `$HOME/.cluster-api/overrides/<provi
 Providers can use variables in the components YAML published in the provider's repository. 
 
 During `clusterctl init`, those variables are replaced with environment variables or with variables read from the 
-[clusterctl configuration](configuring-clusterctl.md).
+[clusterctl configuration](../configuration.md).
 
 <aside class="note warning">
 

docs/book/src/clusterctl/commands.md renamed to docs/book/src/clusterctl/commands/commands.md

@@ -1,18 +1,17 @@
 # clusterctl Configuration File
 
-The `clusterctl` config file is located at `$HOME/.cluster-api/clusterctl.yaml` and it can be used for:
+The `clusterctl` config file is located at `$HOME/.cluster-api/clusterctl.yaml` and it can be used to:
 
-- Customizing the list of providers and provider repositories that `clusterctl` can use
-- Providing values to be used for variable substitution when installing providers or creating clusters
+- Customize the list of providers and provider repositories.
+- Provide configuration values to be used for variable substitution when installing providers or creating clusters.
 
 ## Provider repositories
 
-The `clusterctl` CLI is designed to work with all the providers implementing
-the [clusterct Provider Contract](contract.md).
+The `clusterctl` CLI is designed to work with providers implementing the [clusterct Provider Contract](contract.md).
 
 Each provider is expected to define a provider repository, a well-known place where release assets are published. 
 
-The `clusterctl` CLI ships with providers sponsored by SIG Cluster Lifecycle. 
+By default, `clusterctl` ships with providers sponsored by SIG Cluster Lifecycle. 
 
 Users can customize the list of available providers using the `clusterctl` configuration file, as shown in the following example:
 
@@ -31,10 +30,10 @@ providers:
 ## Variables
 
 When installing a provider `clusterctl` reads a YAML file that is published in the provider repository; while executing
-this operation, `clusterctl` supports variable substitution e.g. for injecting the infrastructure provider credentials.  
+this operation, `clusterctl` can perform substitute certain variables with the ones provided by the user.   
 
-The same mechanism apply also when `clusterctl` reads the cluster templates YAML published in the repository, eg. 
-for injecting the Kubernetes version to use or the number of worker machines to create.
+The same mechanism also applies when `clusterctl` reads the cluster templates YAML published in the repository, e.g. 
+when injecting the Kubernetes version to use. or the number of worker machines to create.
 
 The user can provide values using OS environment variables, but it is also possible to add
 variables in the `clusterctl` config file:

docs/book/src/clusterctl/config-cluster.md renamed to docs/book/src/clusterctl/commands/config-cluster.md

@@ -45,9 +45,9 @@ You can now run the local-overrides hack from the root of the local copy of Clus
 cmd/clusterctl/hack/local-overrides.py
 ```
 
-The script reads from the local repositories of the providers you want to install, builds the providers assets,
-and place them in a local override folder located under `$HOME/.cluster-api/overrides/`.
-Additionally, the command output provide you `clusterctl init` command with all the necessary flags.
+The script reads from the local repositories of the providers you want to install, builds the providers' assets,
+and places them in a local override folder located under `$HOME/.cluster-api/overrides/`.
+Additionally, the command output provides you the `clusterctl init` command with all the necessary flags.
 
 ```shell
 clusterctl local overrides generated from local repositories for the cluster-api, kubeadm-bootstrap, aws providers.

docs/book/src/clusterctl/delete.md renamed to docs/book/src/clusterctl/commands/delete.md

@@ -26,7 +26,7 @@ See the [kind documentation](https://kind.sigs.k8s.io/) for more details.
 {{#/tab }}
 {{#tab kind for docker provider}}
 
-If if are planning to use the Docker infrastructure provider a custom kind cluster configuration is required in order to
+If planning to use the Docker infrastructure provider a custom kind cluster configuration is required in order to
 because the provider needs to access Docker on the host:
 
   ```bash
@@ -270,9 +270,9 @@ See [`clusterctl config cluster`](config-cluster.md) for more details.
 
 The `clusterctl` command supports also day 2 operations:
 
-* use [`clusterctl init`](init.md) to install additional Cluster API providers
-* use [`clusterctl upgrade`](upgrade.md) to upgrade Cluster API providers
-* use [`clusterctl delete`](delete.md) to delete Cluster API providers
+* use [`clusterctl init`](commands/init.md) to install additional Cluster API providers
+* use [`clusterctl upgrade`](commands/upgrade.md) to upgrade Cluster API providers
+* use [`clusterctl delete`](commands/delete.md) to delete Cluster API providers
 
-* use [`clusterctl config cluster`](config-cluster.md) to spec out additional workload clusters
-* use [`clusterctl move`](move.md) to migrate objects defining a workload clusters (e.g. Cluster, Machines) from a management cluster to another management cluster
+* use [`clusterctl config cluster`](commands/config-cluster.md) to spec out additional workload clusters
+* use [`clusterctl move`](commands/move.md) to migrate objects defining a workload clusters (e.g. Cluster, Machines) from a management cluster to another management cluster

docs/book/src/clusterctl/init.md renamed to docs/book/src/clusterctl/commands/init.md

@@ -10,7 +10,7 @@ a provider are published.
 The provider repository MUST contain the following files:
 
 * The metadata YAML
-* The component YAML
+* The components YAML
 
 
 Additionally, the provider repository SHOULD contain the following files:
@@ -30,7 +30,7 @@ If, as a provider implementer, you are interested to be added to this list, plea
 
 <h1>Customizing the list of providers</h1>
 
-It is possible to customize the list of providers for `clusterctl` by changing the [clusterctl configuration](configuring-clusterctl.md).
+It is possible to customize the list of providers for `clusterctl` by changing the [clusterctl configuration](configuration.md).
 
 </aside>
 
@@ -73,7 +73,7 @@ The following rules apply:
 #### Naming conventions
 
 It is strongly recommended that:
-* Core providers release a file called `core-components.yaml`
+* Core provider release a file called `core-components.yaml`
 * Infrastructure providers release a file called `infrastructure-components.yaml`
 * Bootstrap providers release a file called ` bootstrap-components.yaml`
 * Control plane providers release a file called `control-plane-components.yaml`