Update landing pages for reference and how-to

docs/how-to/index.rst

@@ -9,21 +9,17 @@ How-to guides
 Manage the full operations lifecycle of the ``cloudflared`` charms, from initial deployment through
 production maintenance.
 
-DNS and networking
-------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   Configure DNS <configure-dns>
-   Expose a front-end application <expose-frontend>
-
 Charm operations
 ----------------
 
+Understanding operational tasks, such as configuration and backup,
+is essential to use the Cloudflared charms.
+
 .. toctree::
    :maxdepth: 1
 
+   Configure DNS <configure-dns>
+   Expose a front-end application <expose-frontend>
    Use the configurator charm <use-configurator>
    Integrate with COS <integrate-with-cos>
    Back up and restore <back-up-restore>
@@ -34,6 +30,9 @@ Charm operations
 Development and community
 -------------------------
 
+Discover how to resolve common deployment issues and contribute
+any bug fixes or features to the Cloudflared charms.
+
 .. toctree::
    :maxdepth: 1
 

docs/reference/cryptographic-overview.rst

@@ -1,10 +1,10 @@
 .. meta::
-   :description: An overview of the cryptographic components used by the Cloudflared charms.
+   :description: An overview of the security and cryptographic components used by the Cloudflared charms.
 
 .. _reference_cryptographic_overview:
 
-Cryptographic overview
-======================
+Security and cryptographic overview
+===================================
 
 The charms do not implement cryptographic protocols. Juju protects the tunnel
 credential as a `secret <https://canonical.com/juju/docs/juju-cli/3.6/reference/secret/>`_,

docs/reference/index.rst

@@ -6,15 +6,15 @@
 Reference
 =========
 
-This section contains technical details about the ``cloudflared`` subordinate
-machine charm and the ``cloudflare-configurator`` charm. It documents their
-configuration, actions, events, relations, and operational interfaces.
+Technical specifications and architectural details about the `cloudflared`
+subordinate charm and the `cloudflare-configurator` charm.
 
 Charm usage
 -----------
 
-The following pages provide reference information for deploying and integrating
-the charms.
+Operators control charm behavior through configuration options, Juju actions,
+and Juju integrations. Learn the inner workings of the charm, which can help
+you understand the current charm configuration interface and debug problems.
 
 .. vale Canonical.013-Spell-out-numbers-below-10 = NO
 .. vale Canonical.500-Repeated-words = NO
@@ -35,23 +35,13 @@ the charms.
 Architecture and deployments
 ----------------------------
 
-These pages describe the subordinate workload, the configurator, and their
-relations to a principal application.
+Peek into the design and architecture of the charm, which is useful if you want to
+audit or contribute to the Cloudflared charm project.
 
 .. toctree::
     :hidden:
     :maxdepth: 1
 
     Charm architecture <charm-architecture>
     High-level deployment overview <high-level-deployment>
-
-Advanced topics
----------------
-
-These pages cover cryptographic boundaries.
-
-.. toctree::
-    :hidden:
-    :maxdepth: 1
-
-    Cryptographic overview <cryptographic-overview>
+    Security and cryptographic overview <cryptographic-overview>