better wording related to YAML 1.1 content per reviews

doc/rtd/explanation/configuration.rst

@@ -11,22 +11,26 @@ higher priority source overwrites the lower priority source.
 Base configuration
 ==================
 
+The base configuration format uses `YAML version 1.1`_, but may be
+declared as jinja templates which cloud-init will render at runtime with
+:ref:`instance data <instancedata-Using>` variables.
+
 From lowest priority to highest, configuration sources are:
 
-- **Hardcoded config**: Config_ that lives within the source of ``cloud-init``
+- **Hardcoded config** Config_ that lives within the source of ``cloud-init``
   and cannot be changed.
 - **Configuration directory**: Anything defined in :file:`/etc/cloud/cloud.cfg`
-  and :file:`/etc/cloud/cloud.cfg.d`.
+  and :file:`/etc/cloud/cloud.cfg.d/*.cfg`.
 - **Runtime config**: Anything defined in :file:`/run/cloud-init/cloud.cfg`.
 - **Kernel command line**: On the kernel command line, anything found between
   ``cc:`` and ``end_cc`` will be interpreted as cloud-config user data.
 
 These four sources make up the base configuration.
 
 .. note::
-   The base configuration files must be valid `YAML 1.1`_ syntax and they can
-   be declared as :ref:`jinja templates <instancedata-Using>`.
-
+   While config defined in the base configuration can be overridden by
+   vendor and user data, base configuration sources do not conform
+   strictly to :ref:`#cloud-config<user_data_formats>`.
 
 Vendor and user data
 ====================
@@ -36,11 +40,6 @@ Added to the base configuration are :ref:`vendor data<vendordata>` and
 
 These get fetched from the datasource and are defined at instance launch.
 
-.. note::
-   While config keys defined in the base configuration can be overridden by
-   vendor data and user data, base configuration sources do not conform
-   strictly to :ref:`#cloud-config<user_data_formats>`.
-
 Network configuration
 =====================
 
@@ -84,4 +83,4 @@ images.
 
 .. _Config: https://github.com/canonical/cloud-init/blob/b861ea8a5e1fd0eb33096f60f54eeff42d80d3bd/cloudinit/settings.py#L22
 .. _cloud.cfg template: https://github.com/canonical/cloud-init/blob/main/config/cloud.cfg.tmpl
-.. _YAML 1.1: https://yaml.org/spec/1.1/current.html
+.. _YAML version 1.1: https://yaml.org/spec/1.1/current.html

doc/rtd/explanation/format.rst

@@ -3,29 +3,29 @@
 User data formats
 *****************
 
-User data that will be acted upon by ``cloud-init`` must be in one of the
-following types.
+User data is opaque configuration data provided by a platform to an instance at
+launch to perform supplemental configuration operations on that instance at
+first boot. User data that will be acted upon by ``cloud-init`` must be in one
+of the following types.
 
 .. _user_data_formats-cloud_config:
 
 Cloud config data
 =================
 
-Cloud-config is the simplest way to accomplish some things via user data.
-Using cloud-config syntax, the user can specify certain things in a
-human-friendly format.
+Cloud-config is the preferred user data format. The cloud config format is a
+declarative syntax which uses `YAML version 1.1`_ with keys which describe
+desired instance state. Cloud-config can be used to define how an instance
+should be configured in a human-friendly format.
 
-These things include:
+These things may include:
 
-- ``apt upgrade`` should be run on first boot
-- a different ``apt`` mirror should be used
-- additional ``apt`` sources should be added
-- certain SSH keys should be imported
+- performing package upgrades on first boot
+- configuration different package mirrors or sources
+- initial user or group setup
+- importing certain SSH keys or host keys to configure
 - *and many more...*
 
-.. note::
-   This file must be valid `YAML 1.1`_ syntax.
-
 See the :ref:`yaml_examples` section for a commented set of examples of
 supported cloud config formats.
 
@@ -221,6 +221,6 @@ appliances. Setting ``allow_userdata: false`` in the configuration will disable
 ``cloud-init`` from processing user data.
 
 .. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py
-.. _YAML 1.1: https://yaml.org/spec/1.1/current.html
+.. _YAML version 1.1: https://yaml.org/spec/1.1/current.html
 .. [#] See your cloud provider for applicable user-data size limitations...
 .. _this blog post: http://foss-boss.blogspot.com/2011/01/advanced-cloud-init-custom-handlers.html

doc/rtd/explanation/instancedata.rst

@@ -71,7 +71,6 @@ Using ``instance-data``
 * Command line interface via :command:`cloud-init query` or
   :command:`cloud-init devel render`.
 
-
 The aforementioned configuration sources support jinja template rendering.
 When the first line of the provided configuration begins with
 **## template: jinja**, ``cloud-init`` will use jinja to render that file.