From e8436898ac9e031707303f07ab9a40abfeb4c76a Mon Sep 17 00:00:00 2001
From: Surya Murugaian <surya.murugaian@aiven.io>
Date: Wed, 13 Sep 2023 21:02:16 +0000
Subject: [PATCH] updating the editorial corrections

---
 docs/platform/howto/add-storage-space.rst | 40 +++++++++++++----------
 docs/platform/howto/scale-services.rst    |  2 +-
 2 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/docs/platform/howto/add-storage-space.rst b/docs/platform/howto/add-storage-space.rst
index 8f20e1b1e2..73d9ece857 100644
--- a/docs/platform/howto/add-storage-space.rst
+++ b/docs/platform/howto/add-storage-space.rst
@@ -1,19 +1,23 @@
 Add or remove storage 
 =======================
 
-With :doc:`dynamic disk sizing <../concepts/dynamic-disk-sizing>`, you can add or remove disk storage (by factor of 10 GiB only) both when you create a service and later for a running service. But, it is not possible to add or remove storage when the service nodes are rebalancing.(i.e, during maintenance update, service upgrade, etc.)
+With :doc:`dynamic disk sizing <../concepts/dynamic-disk-sizing>`, you can add or remove disk storage (by factor of 10 GiB) both when you create a service and later for a running service.
 
 .. note::
-   This feature is not available for all service plans.
+   - You cannot add or remove storage when service nodes are in the rebalancing state, for example, during a maintenance update or a service upgrade.
+   - This feature is not available for all service plans.
+
+Use Aiven console
+-----------------
 
 Add storage during new service creation
------------------------------------------
+'''''''''''''''''''''''''''''''''''''''
 
 You can add disk storage when :doc:`creating a new service <../howto/create_new_service>`. 
 
 
 Add storage to a running service
----------------------------------
+''''''''''''''''''''''''''''''''
 
 You can add storage to your running service in `Aiven Console <https://console.aiven.io/>`_ without interrupting the service. 
 
@@ -25,12 +29,12 @@ You can add storage to your running service in `Aiven Console <https://console.a
 
 #. In the **Upgrade service storage** window, use the slider to add disk storage.
 
+#. Select **Save changes**.
+
 .. note::
       
       The price shown for the additional storage includes backup costs.
 
-#. Select **Save changes**.
-
 .. topic:: Result
    
    The additional storage is available for immediate use.  
@@ -40,18 +44,18 @@ You can add storage to your running service in `Aiven Console <https://console.a
    Storage optimization is performed at the next maintenance update after a change to the storage size. Due to cloud provider limitations, there is a limit on how many times storage can be increased between two maintenance updates. When this limit is reached, you need to perform a maintenance update for performance optimization. It's best to carefully plan increases to avoid reaching this limit.
 
 Remove additional storage
----------------------------
+'''''''''''''''''''''''''
 
 You can remove storage that you previously added to a service.
 
 Before you start
-''''''''''''''''
+""""""""""""""""
 
 - Make sure the data in your service does not exceed your service plan's allocated storage. If it does, you will not be able to remove the additional storage. 
 - Plan for the time it takes to recycle the nodes. The service will be in a rebalancing state after removing storage. The time it takes depends on the service. 
 
 Remove added storage
-''''''''''''''''''''
+""""""""""""""""""""
 
 #. Log in to `Aiven Console <https://console.aiven.io/>`_, and go to your project.
 
@@ -70,17 +74,17 @@ Remove added storage
 
    Your additional disk space has been removed. The service is in the **Rebalancing** state while the nodes are being recycled. 
 
-Using Aiven CLI
----------------
+Use Aiven CLI
+-------------
 
-It is possible to use :doc:`Aiven CLI </docs/tools/cli>` to add or remove additional storage by :ref:`updating the service configuration <avn-cli-service-update>` using the flag ``--disk-space-gib``. The value here is the total disk space that your service would like to have.
-For example, if you are using a ``Startup-4`` plan which has 80GB disk space by default and you would like to add extra 10GB disk. The value to be given for the flag ``--disk-space-gib`` is 90 GB.
-::
+You can use :doc:`Aiven CLI </docs/tools/cli>` to add or remove additional storage by :ref:`updating the service configuration <avn-cli-service-update>` using command ``avn service update`` with flag ``--disk-space-gib``. Specify the value for the flag as the total disk space that you need for your service.
+For example, if you use a ``Startup-4`` plan with a 80-GiB disk by default and you would like to add an extra 10-GiB disk, the value that the ``--disk-space-gib`` flag requires is ``90``.
 
-      avn service update --disk-space-gib 90 --project <PROJECT_NAME> <SERVICE_NAME>
+.. code-block:: bash
 
-.. note::
+      avn service update --disk-space-gib 90 --project PROJECT_NAME SERVICE_NAME
 
-   - When you perform a service upgrade or downgrade horizontally, it is required to include any additional disk existing on the service. For example, ``Startup-4`` to ``Business-4`` or ``Business-4`` to ``Startup-4``.
-   - Similarly, when you fork an existing service, it is required to include any additional disk on the source service.
+.. note::
 
+   - When you perform a service upgrade or downgrade horizontally, remember to include all additional disks the service uses. For example, when switching from ``Startup-4`` to ``Business-4`` or from ``Business-4`` to ``Startup-4``, include all the additional disks available for this service.
+   - Similarly, when you fork an existing service, include all additional disks the service uses.
\ No newline at end of file
diff --git a/docs/platform/howto/scale-services.rst b/docs/platform/howto/scale-services.rst
index 916c3c2b61..3c3e7d2223 100644
--- a/docs/platform/howto/scale-services.rst
+++ b/docs/platform/howto/scale-services.rst
@@ -17,4 +17,4 @@ When creating a new Aiven service, you are not tied to a plan. Your services can
 .. note::
 
     - You can also use the :ref:`dedicated service update function <avn-cli-service-update>` to scale your service plan via the :doc:`Aiven CLI </docs/tools/cli>`.
-    - When you perform a service upgrade or downgrade horizontally, it is required to include any additional disk existing on the service. For example, ``Startup-4`` to ``Business-4`` or ``Business-4`` to ``Startup-4``.
+    - When you perform a service upgrade or downgrade horizontally, remember to include all additional disks the service uses. For example, when switching from ``Startup-4`` to ``Business-4`` or from ``Business-4`` to ``Startup-4``, include all the additional disks available for this service.