canonical · sabaini · Oct 17, 2023 · Oct 13, 2023 · Oct 16, 2023
diff --git a/docs/explanation/cluster-cfg.rst → docs/explanation/cluster-configurations.rst b/docs/explanation/cluster-cfg.rst → docs/explanation/cluster-configurations.rst
@@ -1,5 +1,6 @@
-Cluster Network Configurations in MicroCeph
-===========================================
+==============================
+Cluster network configurations
+==============================
 
 Overview
 --------

diff --git a/docs/explanation/scaling.rst → docs/explanation/cluster-scaling.rst b/docs/explanation/scaling.rst → docs/explanation/cluster-scaling.rst
@@ -1,5 +1,6 @@
-Scaling
-=================
+===============
+Cluster scaling
+===============
 
 
 Overview

diff --git a/docs/explanation/fde-osd.rst → docs/explanation/full-disk-encryption.rst b/docs/explanation/fde-osd.rst → docs/explanation/full-disk-encryption.rst
@@ -1,5 +1,6 @@
-Full Disk Encryption on OSDs
-============================
+====================
+Full disk encryption
+====================
 
 
 Overview

diff --git a/docs/explanation/snap-content-interface.rst b/docs/explanation/snap-content-interface.rst
@@ -1,5 +1,6 @@
-MicroCeph Content Interface
-===========================
+====================================
+Snap content interface for MicroCeph
+====================================
 
 Overview
 --------

diff --git a/docs/how-to/cluster-cfg.rst → docs/how-to/configure-network-keys.rst b/docs/how-to/cluster-cfg.rst → docs/how-to/configure-network-keys.rst
@@ -1,5 +1,6 @@
-Configure cluster_network/ public_network in MicroCeph
-======================================================
+========================
+Configuring network keys
+========================
 
 The MicroCeph cluster configuration CLI supports setting, getting, resetting and listing supported config keys mentioned below.
 
@@ -56,5 +57,5 @@ The MicroCeph cluster configuration CLI supports setting, getting, resetting and
    | # | KEY | VALUE |
    +---+-----+-------+
 
-For more explanations and implementation details refer to :doc:`explanation <../explanation/cluster-cfg>`
+For more explanations and implementation details refer to :doc:`explanation <../explanation/cluster-configurations>`
 
diff --git a/docs/how-to/alerts.rst → docs/how-to/enable-alerts.rst b/docs/how-to/alerts.rst → docs/how-to/enable-alerts.rst
@@ -1,9 +1,10 @@
-Enable alerts on MicroCeph using Prometheus Alertmanager
-========================================================
+=======================================
+Enabling Prometheus Alertmanager alerts
+=======================================
 
 Pre-Requisite
 -------------
-In order to configure alerts, your MicroCeph deployment must enable metrics collections with Prometheus. Follow :doc:`this How-To <metrics>` if you haven't configured it. Also, Alertmanager is distributed as a separate binary which should be installed and running.
+In order to configure alerts, your MicroCeph deployment must enable metrics collections with Prometheus. Follow :doc:`this How-To <enable-metrics>` if you haven't configured it. Also, Alertmanager is distributed as a separate binary which should be installed and running.
 
 Introduction
 ------------

diff --git a/docs/how-to/metrics.rst → docs/how-to/enable-metrics.rst b/docs/how-to/metrics.rst → docs/how-to/enable-metrics.rst
@@ -1,5 +1,6 @@
-Enable MicroCeph metrics collection with Prometheus
-===================================================
+===========================================
+Enabling metrics collection with Prometheus
+===========================================
 
 Introduction
 ------------

diff --git a/docs/how-to/service-placement.rst → docs/how-to/enable-service-instances.rst b/docs/how-to/service-placement.rst → docs/how-to/enable-service-instances.rst
@@ -1,6 +1,6 @@
-===================================
-Enable additional service instances
-===================================
+=====================================
+Enabling additional service instances
+=====================================
 
 To ensure a base level of resiliency, MicroCeph will always try to enable a
 sufficient number of instances for certain services in the cluster. This

diff --git a/docs/how-to/service-migration.rst → docs/how-to/migrate-auto-services.rst b/docs/how-to/service-migration.rst → docs/how-to/migrate-auto-services.rst
@@ -1,6 +1,6 @@
-==========================================
-Migrate automatically-provisioned services
-==========================================
+============================================
+Migrating automatically-provisioned services
+============================================
 
 MicroCeph deploys automatically-provisioned Ceph services when needed. These
 services include:

diff --git a/docs/how-to/remove-disk.rst b/docs/how-to/remove-disk.rst
@@ -1,6 +1,6 @@
-=============
-Remove a disk
-=============
+===============
+Removing a disk
+===============
 
 Overview
 --------
@@ -12,7 +12,7 @@ the removal of a cluster node (machine).
 
 The following resources provide extra context to the disk removal operation:
 
-* the :doc:`../../explanation/scaling` page
+* the :doc:`../../explanation/cluster-scaling` page
 * the :doc:`disk <../reference/commands/disk>` command reference
 
 .. note::

diff --git a/docs/tutorial/multi-node.rst b/docs/tutorial/multi-node.rst
@@ -1,6 +1,6 @@
-==========
-Multi-node
-==========
+==================
+Multi-node install
+==================
 
 This tutorial will show how to install MicroCeph on three machines, thereby
 creating a multi-node cluster.

diff --git a/docs/tutorial/single-node.rst b/docs/tutorial/single-node.rst
@@ -1,6 +1,6 @@
-===========
-Single-node
-===========
+===================
+Single-node install
+===================
 
 This tutorial will show how to install MicroCeph on a single machine, thereby
 creating a single-node "cluster".
@@ -13,9 +13,8 @@ three entire disks are required to be available on the machine.
 
 .. note::
 
-   Development is underway to allow for loopback device support.
-   This will filter down to MicroCeph which will allow for easier
-   proof-of-concept and developer deployments.
+   Development is underway to allow for loopback device support. This will
+   allow for easier proof-of-concept and developer deployments.
 
 The disk subsystem can be inspected with the :command:`lsblk` command. In this
 tutorial, the command's output is shown below. Any output related to possible