diff --git a/docs/guide/cli/cli_basics.rst b/docs/guide/cli/cli_basics.rst
index 56f5602d0..14aa5997f 100644
--- a/docs/guide/cli/cli_basics.rst
+++ b/docs/guide/cli/cli_basics.rst
@@ -3,11 +3,12 @@ CLI basics
 
 The ``openfe`` command consists of several subcommands. This is similar to
 tools like ``gmx``, which has subcommands like ``gmx mdrun``, or ``conda``,
-which has subcommands like ``conda install``. To get a list of the
-subcommands and a brief description of them, use ``openfe (or
-``openfe -h``), which will give:
+which has subcommands like ``conda install``.
 
-.. TODO autogemerate using sphinxcontrib-programoutput
+To get a list of the subcommands and their descriptions, call ``openfe`` (or
+``openfe -h``):
+
+.. TODO autogenerate using sphinxcontrib-programoutput
 
 .. code:: none
 
diff --git a/docs/guide/cli/cli_yaml.rst b/docs/guide/cli/cli_yaml.rst
index b69493686..6e047e774 100644
--- a/docs/guide/cli/cli_yaml.rst
+++ b/docs/guide/cli/cli_yaml.rst
@@ -1,10 +1,11 @@
-Customising CLI planning with yaml settings
+Customising CLI planning with YAML settings
 ===========================================
 
 The planning commands in the CLI can be made more powerful by supplying
-"yaml" formatted files to customise the planning algorithms.
-This settings file has a series of sections for customising the different algorithms,
-as an example, the settings file which re-specifies the default behaviour would look like ::
+YAML-formatted files to customise the planning algorithms.
+
+This settings file has a series of sections for customising the different algorithms.
+For example, the settings file which re-specifies the default behaviour would look like ::
 
   network:
     method: plan_minimal_spanning_tree
@@ -18,9 +19,9 @@ as an example, the settings file which re-specifies the default behaviour would
 
 The name of the algorithm is given behind the ``method:`` key and the arguments to the
 algorithm are then optionally given behind the ``settings:`` key.
-Both the `network:` and `mapper:` sections are optional.
+Both the ``network:`` and ``mapper:`` sections are optional.
 
-This is then provided to the ``openfe plan-rbfe-network`` command as ::
+The settings YAML file is then provided to the ``-s`` option of ``openfe plan-rbfe-network``: ::
 
   openfe plan-rbfe-network -M molecules.sdf -P protein.pdb -s settings.yaml
 
@@ -28,8 +29,11 @@ Customising the atom mapper
 ---------------------------
 
 There is a choice to be made as to which atom mapper is used,
-currently included are the :class:`.LomapAtomMapper` and the :class:`.KartografAtomMapper`
-For example to switch to using the ``Kartograf`` atom mapper, this settings yaml could be used ::
+currently included are the :class:`.LomapAtomMapper` and the :class:`.KartografAtomMapper` (full details in the `Kartograf documentation`_.)
+
+.. _Kartograf documentation: https://kartograf.readthedocs.io/en/latest/api/kartograf.mappers.html#kartograf.atom_mapper.KartografAtomMapper
+
+For example, to switch to using the ``Kartograf`` atom mapper, this settings YAML could be used ::
 
   mapper:
     method: KartografAtomMapper
@@ -39,9 +43,6 @@ For example to switch to using the ``Kartograf`` atom mapper, this settings yaml
       map_hydrogens_on_hydrogens_only: False
       map_exact_ring_matches_only: True
 
-Full details on these options can be found in the `Kartograf documentation`_.
-
-.. _Kartograf documentation: https://kartograf.readthedocs.io/en/latest/api/kartograf.mappers.html#kartograf.atom_mapper.KartografAtomMapper
 
 Customising the network planner
 -------------------------------
@@ -51,7 +52,7 @@ There are a variety of network planning options available, including
 :func:`.generate_minimal_spanning_network`, and
 :func:`.generate_minimal_redundant_network`.
 
-For example to plan a radial network using a ligand called 'CHEMBL1078774' as the central ligand, this settings yaml
+For example, to plan a radial network using a ligand called 'CHEMBL1078774' as the central ligand, this settings YAML
 could be given ::
 
   network:
@@ -69,7 +70,7 @@ To select the first ligand, the **integer** 0 can be given ::
     settings:
       central_ligand: 0
 
-Whereas if we wanted to specify the ligand named "0", we would instead explicitly pass this as **a string** to the yaml
+Whereas if we wanted to specify the ligand named "0", we would instead explicitly pass this as **a string** to the YAML
 settings file ::
 
   network: