doc/cephadm: improving "Monitoring the Upgrade"

This PR improves the section "Monitoring the Upgrade"
in the "Upgrading Ceph" chapter of the cephadm documentation.

This PR introduces a couple of section breaks with signposting
information in their titles, and rewrites some sentences in order
to reduce the cognitive load of the reader.

Signed-off-by: Zac Dover <zac.dover@gmail.com>

diff --git a/doc/cephadm/upgrade.rst b/doc/cephadm/upgrade.rst
index 8b6023e82ad5e16a88aa7f8b23857ef9370d8bb8..c7d38c49d993fa18730092f3bdbaebdc04b3d7bb 100644 (file)
--- a/doc/cephadm/upgrade.rst
+++ b/doc/cephadm/upgrade.rst
@@ -41,28 +41,32 @@ For example, to upgrade to v15.2.1:
 Monitoring the upgrade
 ======================
 
-Determine whether an upgrade is in process and what version the cluster is
-upgrading to with:
+Determine (1) whether an upgrade is in progress and (2) which version the
+cluster is upgrading to by running the following command:
 
 .. prompt:: bash #
 
   ceph orch upgrade status
 
-While the upgrade is underway, you will see a progress bar in the ceph
-status output. For example:
+Watching the progress bar during a Ceph upgrade
+-----------------------------------------------
 
-.. prompt:: bash #
+During the upgrade, a progress bar is visible in the ceph status output. It
+looks like this:
 
-  ceph -s
+.. code-block:: console
 
-Expected output::
+  # ceph -s
 
   [...]
     progress:
       Upgrade to docker.io/ceph/ceph:v15.2.1 (00h 20m 12s)
         [=======.....................] (time remaining: 01h 43m 31s)
 
-You can also watch the cephadm log by running the following command:
+Watching the cephadm log during an upgrade
+------------------------------------------
+
+Watch the cephadm log by running the following command:
 
 .. prompt:: bash #