[discourse-gatekeeper] Migrate charm docs (#115)

Co-authored-by: upload-charms-docs-bot <upload-charms-docs-bot@users.noreply.github.com>

docs/how-to/h-deploy.md

@@ -1,104 +1,111 @@
 # How to deploy Charmed Kafka K8s
 
-To deploy a Charmed Kafka K8s cluster on a bare environment, it is necessary to:
+> **IMPORTANT** For non-K8s Charmed Kafka, see the [Charmed Kafka documentation](/t/charmed-kafka-documentation/13261) instead.
+
+To deploy a Charmed Kafka K8s cluster:
 1. Set up a Juju Controller
 2. Set up a Juju Model
-3. Deploy Charmed Kafka K8s and Charmed ZooKeeper K8s
+3. Deploy and relate Kafka K8s and ZooKeeper K8s charms.
 4. (Optionally) Create an external admin user
 
-In the next subsections we will cover these steps separately by referring to 
-relevant Juju documentation and providing details on the Charmed Kafka K8s specifics.
-If you already have a Juju controller and/or a Juju model, you can skip the associated steps.
-
 ## Juju Controller setup
 
-Before deploying Kafka, make sure you have a Juju controller accessible from 
+Make sure you have a Juju controller accessible from 
 your local environment using the [Juju client snap](https://snapcraft.io/juju). 
 
-The properties of your current controller can be listed using `juju show-controller`. 
-Make sure that the controller's backend cloud **is** K8s. 
-The cloud information can be retrieved with the following command
+List available controllers:
+
+```commandline
+juju list-controllers
+```
+
+Switch to another controller if needed:
+
+```commandline
+juju switch <controller>
+```
+
+If there are no suitable controllers, create a new one:
 
 ```commandline
-juju show-controller | yq '.[].details.cloud'
+juju bootstrap <cloud> <controller>
 ```
 
-> **IMPORTANT** If the cloud is **not** `k8s`, please refer to the [Charmed Kafka documentation](/t/charmed-kafka-documentation/10288) instead.
+where `<cloud>` -- the cloud to deploy controller to, e.g., `localhost`. For more information on how to setup a new cloud, see the [How to manage clouds](https:///t/1100) guide in Juju documentation.
 
-You can find more information on how to bootstrap and configure a controller for different 
-clouds [here](https://juju.is/docs/juju/manage-controllers#heading--bootstrap-a-controller). 
-Make sure you bootstrap a `k8s` Juju controller. 
+> **Note** See the [How to manage controllers](/t/1111) guide in Juju documentation for more options.
 
 ## Juju Model setup
 
 You can create a new Juju model using 
 
-```
+```commandline
 juju add-model <model>
 ```
 
-Alternatively, you can use a pre-existing Juju model and switch to it by running the following command: 
+Alternatively, you can switch to any existing Juju model: 
 
-```
-juju switch <model-name>
+```commandline
+juju switch <model>
 ```
 
-Make sure that the model is **not** a `k8s` type. The type of the model 
-can be obtained by 
+Make sure that the model is of a correct type (`k8s`):
 
-```
+```commandline
 juju show-model | yq '.[].type'
 ```
 
-> **IMPORTANT** If the model is **not** `k8s`, please refer to the [Charmed Kafka documentation](/t/charmed-kafka-documentation/10288) instead.
-
-
-## Deploy Charmed Kafka K8s and Charmed ZooKeeper
+## Deploy and relate Kafka K8s and ZooKeeper charms
 
 The Kafka and ZooKeeper charms can both be deployed as follows:
 
-```shell
-$ juju deploy zookeeper-k8s --channel 3/edge -n <zookeeper-units>
-$ juju deploy kafka-k8s --channel 3/edge -n <kafka-units>
+```commandline
+juju deploy kafka-k8s --channel 3/edge -n <kafka-units>
+juju deploy zookeeper-k8s --channel 3/edge -n <zookeeper-units>
 ```
 
-After this, it is necessary to connect them:
-```shell
-$ juju relate kafka-k8s zookeeper-k8s
+where `<kafka-units>` and `<zookeeper-units>` -- the number of units to deploy for Kafka and ZooKeeper. We recommend values of at least `3` and `5` respectively.
+
+Connect ZooKeeper and Kafka by relating/integrating the charms:
+
+```commandline
+juju relate kafka-k8s zookeeper-k8s
 ```
 
-> We recommend values for `<kafka-units>` of at least 3 and for `<zookeeper-units>` of 5, to 
-ensure reasonable high-availability margins.
+Check the status of the deployment:
+
+```commandline
+juju status
+```
 
-Once all the units show as `active|idle` in the `juju status` output, the deployment 
-should be ready to be used. 
+Once all the units show `active` or `idle` status, the deployment should be complete. 
 
 ## (Optional) Create an external admin users
 
 Charmed Kafka aims to follow the _secure by default_ paradigm. As a consequence, after being deployed the Kafka cluster
 won't expose any external listener. 
 In fact, ports are only opened when client applications are related, also 
-depending on the protocols to be used. Please refer to [this table](TODO) for 
-more information about the available listeners and protocols. 
+depending on the protocols to be used. 
+> **NOTE** For more information about the available listeners and protocols please refer to [this table](/t/13270). 
 
-It is however generally useful for most of the use-cases to create a first admin user
+It is however generally useful for most situations to create a first admin user
 to be used to manage the Kafka cluster (either internally or externally). 
 
 To create an admin user, deploy the [Data Integrator Charm](https://charmhub.io/data-integrator) with 
-`extra-user-roles` set to `admin`
+`extra-user-roles` set to `admin`:
 
-```shell
+```commandline
 juju deploy data-integrator --channel stable --config topic-name=test-topic --config extra-user-roles=admin
 ```
 
-and relate to the Kafka charm
+... and relate it to the Kafka charm:
 
-```shell
+```commandline
 juju relate data-integrator kafka-k8s
 ```
 
-To retrieve authentication information such as the username, password, etc. use
+To retrieve authentication information, such as the username and password, use:
 
-```shell
+```commandline
 juju run data-integrator/leader get-credentials
 ```

docs/index.md

@@ -1,27 +1,27 @@
-# Charmed Kafka K8s Documentation
+# Charmed Kafka K8s documentation
 
 Charmed Kafka K8s is an open-source operator that makes it easier to manage Apache Kafka on Kubernetes, with built-in support for enterprise features. 
 
 Charmed Kafka K8s is built on top of [Juju](https://juju.is/) and reliably simplifies the deployment, scaling, design, and management of Apache Kafka on Kubernetes in production. Additionally, you can use the charm to manage your Kafka clusters with automation capabilities. It also offers replication, TLS, password rotation, easy-to-use application integration, and monitoring.
 Charmed Kafka K8s operates Apache Kafka on different Kubernetes distributions, featuring support for both on-premise installation (e.g. using MicroK8s) or cloud services (e.g. AWS EKS).
 
 Charmed Kafka K8s is a solution designed and developed for helping ops teams and 
-administrators to automate Apache Kafka operations from day 0 to day 2, across multiple cloud environments and platforms.
+administrators to automate Apache Kafka operations from Day 0 to Day 2, across multiple cloud environments and platforms.
 
 [note]
 Canonical has also developed the [Charmed Kafka operator](/t/charmed-kafka-documentation/10288) to support Kafka in VM/IAAS environments.
 [/note]
 
 Charmed Kafka K8s is developed and supported by [Canonical](https://canonical.com/), as part of its commitment to 
 provide open-source, self-driving solutions, seamlessly integrated using the Operator Framework Juju. Please 
-refer to [charmhub.io](https://charmhub.io/), for more charmed operators integrated in the Juju ecosystem.
+refer to [Charmhub.io](https://charmhub.io/), for more Charmed operators that can be integrated by Juju.
 
 ## In this documentation
 
 | | |
 |--|--|
 |  [Tutorials](/t/charmed-kafka-k8s-tutorial-overview/11945)</br>  Get started - a hands-on introduction to using Charmed Kafka K8s operator for new users </br> |  [How-to guides](/t/charmed-kafka-k8s-how-to-manage-units/10295) </br> Step-by-step guides covering key operations and common tasks |
-| [Reference](https://charmhub.io/kafka-k8s/actions?channel=3/stable) </br> Technical information - specifications, APIs, architecture | [Explanation]() </br> Concepts - discussion and clarification of key topics  |
+| [Reference](/t/13269) </br> Technical information - specifications, APIs, architecture | <!-- [Explanation]() </br> Concepts - discussion and clarification of key topics -->  |
 
 ## Project and community
 
@@ -34,4 +34,4 @@ Charmed Kafka K8s is a distribution of Apache Kafka. It’s an open-source proje
 
 ## License
 
-The Charmed Kafka K8s Operator is free software, distributed under the Apache Software License, version 2.0. See [LICENSE](https://github.com/canonical/kafka-operator/blob/main/LICENSE) for more information.
+The Charmed Kafka K8s Operator is free software, distributed under the Apache Software License, version 2.0. See [LICENSE](https://github.com/canonical/kafka-k8s-operator/blob/main/LICENSE) for more information.

docs/tutorial/t-setup-environment.md

@@ -7,7 +7,7 @@ This is part of the [Charmed Kafka Tutorial](/t/charmed-kafka-k8s-documentation-
 Let's install Multipass from [Snap](https://snapcraft.io/multipass) and launch a new VM using "[charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml)" cloud-init config:
 ```shell
 sudo snap install multipass && \
-multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs
+multipass launch --cpus 4 --memory 8G --disk 50G --name my-vm charm-dev
 ```
 *Note: all 'multipass launch' params are [described here](https://multipass.run/docs/launch-command)*.