Howto reform

howto/install-appliance/google-cloud.md

@@ -14,28 +14,20 @@ Before starting the procedure,
 ## Virtual machine setup
 
 ### 1. Create a virtual machine
-Log in to [Google Cloud](https://console.cloud.google.com) and select the project for this deployment. Select **CREATE INSTANCE** in the **VM instances** page.
-
-![VM instances on Google Cloud|690x440](https://assets.ubuntu.com/v1/f1e83df5-VM-instance-2.png)
-
-Select **New VM instance** from the options on the sidebar.
-
-![VM instance options on Google Cloud|690x440](https://assets.ubuntu.com/v1/b400c919-Instance-options-2.png)
+Log in to [Google Cloud](https://console.cloud.google.com) and select the project for this deployment. Select **VM instances > Create Instance > New VM instance**.
 
 ### 2. Configure basic settings
 
-Configure the following basic settings for the virtual machine. 
-
-* **Name** - Name of the virtual machine instance
-* **Labels** - Organisational labels to keep track of your resources on Google Cloud
-* **Region** and **Zone** - The geographic location where your resources are run and your data is stored
-* **Machine configuration**, **Series**, **Machine type** and **Display device** - Select a machine configuration that matches the hardware requirements. If your requirement includes GPUs, select the GPU-optimised machine configuration. For example, an NVIDIA L4 GPU. You can select the recommended preset machine type or define a custom type with additional cores and memory for an added cost.
+* *Name* - Name of the virtual machine instance
+* *Labels* - Organisational labels to keep track of your resources on Google Cloud
+* *Region* and *Zone* - The geographic location where your resources are run and your data is stored
+* *Machine configuration*, *Series*, *Machine type* and *Display device* - Select a machine configuration that matches the hardware requirements. If your requirement includes GPUs, select the GPU-optimised machine configuration. For example, an NVIDIA L4 GPU. You can select the recommended preset machine type or define a custom type with additional cores and memory for an added cost.
 
 Most of the configuration depends on your deployment and its location. For the settings that are not mentioned in this guide, you can choose to proceed with the default options or see [Google's documentation](https://cloud.google.com/compute/docs/instances/create-start-instance) to customise your virtual machine on Google Cloud.
 
 ### 3. Configure disks
 
-Configure the boot disk by selecting **Boot disk > CHANGE** to choose the operating system and boot disk size.
+Configure the boot disk by selecting **Boot disk > Change** to choose the operating system and boot disk size.
 
 ![Configure boot disk|690x440](https://assets.ubuntu.com/v1/884d0b10-boot-disk-config-2.png)
 
@@ -47,7 +39,7 @@ Select the latest Ubuntu image for the architecture that you want to use. For ex
 
 Define your preferred boot disk size. We recommend allocating at least 100 GB of disk size.
 
-For Anbox Cloud Appliance, adding an additional disk is recommended for efficient container storage. Under **Advanced Options > Disks**, Select **ADD NEW DISK**. Add a disk name and choose the disk size as 100 GB. For the other fields, you can choose your preferred value or proceed with the default values. 
+For Anbox Cloud Appliance, adding an additional disk is recommended for efficient container storage. Under **Advanced Options > Disks**, Select **Add new disk**. Add a disk name and choose the disk size as 100 GB. For the other fields, you can choose your preferred value or proceed with the default values.
 
 ![Add new disk|690x440](https://assets.ubuntu.com/v1/8acf5d22-add-new-disk-2.png)
 
@@ -59,13 +51,15 @@ There are two ways to map the firewall rules to the virtual machine in Google Cl
 
 **Specified target tags** - If you want to use specified target tags to map your firewall rules to the virtual machine, assign a unique network tag under **Advanced options > Networking > Network tags**. This network tag will later be used while creating a firewall rule.
 
+For more information, see [Google's documentation](https://cloud.google.com/firewall/docs/using-firewalls).
+
 ### 5. Launch the virtual machine
 
-Select **CREATE** to create the virtual machine on Google Cloud. For additional information on creating a virtual machine in Google Cloud, see [Google's documentation](https://cloud.google.com/compute/docs/instances/create-start-instance).
+Select **Create** to create the virtual machine on Google Cloud. For additional information on creating a virtual machine in Google Cloud, see [Google's documentation](https://cloud.google.com/compute/docs/instances/create-start-instance).
 
 ## Firewall setup
 
-Before installing Anbox Cloud on the virtual machine, you should set up a firewall to control the incoming and outgoing traffic to your virtual machine. From the navigation menu, select **VPC network > Firewall**. Select **CREATE FIREWALL RULE**. 
+Before installing Anbox Cloud on the virtual machine, you should set up a firewall to control the incoming and outgoing traffic to your virtual machine. From the navigation menu, select **VPC network > Firewall**. Select **Create firewall rule**.
 
 You can create a firewall rule based on your networking requirements following [Google's documentation](https://cloud.google.com/firewall/docs/using-firewalls). The following is an example firewall rule to enable access to the Anbox Cloud Appliance dashboard once the appliance is installed on the virtual machine. 
 
@@ -90,15 +84,15 @@ The target tag `foo` will be used as the network tag in the virtual machine sett
 
 If you want to use the service account to map the firewall rule to the instance, choose `Targets` as `Specified service account` and use the service account configured in the virtual machine.
 
-Select **CREATE** to create the firewall rule.
+Select **Create** to create the firewall rule.
 
 ## Connect to the virtual machine using SSH
 
 On the virtual machine instance page, connect to the instance using SSH. See [Google's documentation](https://cloud.google.com/compute/docs/ssh-in-browser) for more information. 
 
 ## Finish the installation
 
-Perform the following steps to finish the appliance installation on the virtual machine. If you are not already familiar with how to perform these steps, see the [tutorial on installing the appliance](https://discourse.ubuntu.com/t/22681) for detailed instructions.
+To complete the installation:
 
 1. Install the Anbox Cloud Appliance on the virtual machine.
 
@@ -107,4 +101,6 @@ Perform the following steps to finish the appliance installation on the virtual
 1. Initialise the appliance.
 1. Register your Ubuntu SSO account with the appliance dashboard.
 
+[note type="information" status="Note"]If you are not already familiar with how to perform these steps, see the [tutorial on installing the appliance](https://discourse.ubuntu.com/t/22681) for detailed instructions.[/note]
+
 When you are done, you can log into the appliance dashboard using `https://your-machine-address` with your Ubuntu SSO account.

howto/manage/resize-storage.md

@@ -1,15 +1,15 @@
 Resizing the LXD storage pool that Anbox Cloud uses is not recommended. Before you deploy Anbox Cloud, you should analyse and plan the capacity you need, so that you can size the storage that you need correctly right from the start. See [About capacity planning](https://discourse.ubuntu.com/t/about-capacity-planning/28717) for detailed information.
 
-However, if you run into a situation where you need to grow the LXD storage pool, it depends on your setup if this is actually possible.
+However, if you run into a situation where you need to grow the LXD storage pool, try the following workarounds depending on your setup.
 
 - **Loop-backed storage pool**
 
-  If you use a loop file for your LXD storage, you can increase its size by following the instructions for ZFS in [Resize a storage pool](https://documentation.ubuntu.com/lxd/en/latest/howto/storage_pools/#resize-a-storage-pool) in the LXD documentation.
+  If you use a loop file for your LXD storage, follow the instructions for ZFS in [Resize a storage pool](https://documentation.ubuntu.com/lxd/en/latest/howto/storage_pools/#resize-a-storage-pool) in the LXD documentation.
 
   After resizing the storage pool, you must restart AMS.
 - **Dedicated block device**
 
-  You cannot resize a dedicated block device. In this case, you must replace the block device with a bigger one (which requires re-deploying the cluster node).
+  You cannot resize a dedicated block device. Instead, replace the block device with a bigger one. Once you replace the block device, you must redeploy the cluster node.
 - **EBS volume**
 
-  While it is generally possible to resize an EBS volume, it is usually easier to replace the cluster node with a new one that has a bigger EBS volume.
+  While it is generally [possible to resize an EBS volume](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/requesting-ebs-volume-modifications.html), it is usually easier to replace the cluster node with a new one that has a bigger EBS volume.

howto/update/control.md

@@ -6,6 +6,6 @@ In a production environment, this update behaviour might cause problems in some
 - snapd might automatically update the snap of a prerequisite that is not compatible with the current version of Anbox Cloud.
 - Different nodes of an Anbox Cloud or LXD cluster might end up running different snap versions.
 
-To prevent such problems, you should define maintenance windows in which your systems can be updated without interrupting operations. See [Managing updates](https://snapcraft.io/docs/keeping-snaps-up-to-date) in the snap documentation for information on how to control snap updates on your systems.
-
-Alternatively, you can configure a [Snap Store Proxy](https://docs.ubuntu.com/snap-store-proxy/). Such a proxy makes it possible to control which snaps are served to the machines that use the proxy. In particular, you can use the proxy to [override snap revisions](https://docs.ubuntu.com/snap-store-proxy/en/overrides). With this method, you have full control over when snaps are updated.
+To prevent such problems, use either of the following methods:
+* Define maintenance windows in which your systems can be updated without interrupting operations. See [Managing updates](https://snapcraft.io/docs/keeping-snaps-up-to-date) in the snap documentation for information on how to control snap updates on your systems.
+* Configure a [Snap Store Proxy](https://docs.ubuntu.com/snap-store-proxy/) to control which snaps are served to the machines that use the proxy. In particular, you can use the proxy to [override snap revisions](https://docs.ubuntu.com/snap-store-proxy/en/overrides). In this method, you have full control over when snaps are updated.

howto/update/upgrade-appliance.md

@@ -1,4 +1,4 @@
-Before you upgrade the Anbox Cloud Appliance, you should make sure all packages on the machines that are part of the deployment are up-to-date. To do so, run the following commands on each machine:
+Before you upgrade the Anbox Cloud Appliance, make sure all packages on the machines that are part of the deployment, are up-to-date. To do so, run the following commands on each machine:
 
     sudo apt update
     sudo apt upgrade
@@ -10,9 +10,9 @@ The Anbox Cloud Appliance includes an `upgrade` command which will perform all r
     reboot-needed: false
     version: 1.19.0
 
-[note type="information" status="Important"]While the upgrade process is active API endpoints and the dashboard will not be available. Anbox containers will stay active and existing streams will also not be interrupted.[/note]
+[note type="information" status="Important"]While the upgrade process is active, API endpoints and the dashboard will not be available. Anbox Cloud containers will stay active and existing streams will also not be interrupted.[/note]
 
-In the command output above the `update-available` field indicates an update is available. The upgrade process can now be initiated by running the `upgrade` command:
+In the `anbox-cloud-appliance status` command output, the `update-available` field indicates if an update is available. If an update is available, the upgrade process can now be initiated by running the `upgrade` command:
 
     anbox-cloud-appliance upgrade
 
@@ -24,12 +24,12 @@ You can watch the upgrade progress on the web interface:
 
 ![Upgrade the appliance|690x435](https://assets.ubuntu.com/v1/1093e239-update_appliance.png)
 
- or with the `anbox-cloud-appliance status` command you used above:
+ or with the same `anbox-cloud-appliance status` command that you used earlier:
 
     status: maintenance
     progress: 40
     update-available: false
     reboot-needed: true
     version: 1.19.1
 
-When the upgrade has finished the appliance is again available for regular use.
+When the upgrade is successful, the appliance is again available for regular use.