docs: update how-to and reference landing pages

docs/how-to/index.rst

@@ -6,46 +6,33 @@
 How-to guides
 =============
 
-The following guides cover key processes and common tasks for managing and
-using the aproxy charm.
+Manage the aproxy charm through its full operations lifecycle.
 
 .. vale Canonical.013-Spell-out-numbers-below-10 = NO
 .. vale Canonical.500-Repeated-words = NO
 
 Basic operations
 ----------------
 
-Once you've finished setting up the charm, now you can perform a number
-of actions with your deployment. These guides provide instructions on
-basic operations you can complete with the charm.
+Day-to-day tasks such as configuring proxy settings and integrating with
+observability tools keep your aproxy deployment functioning correctly and
+connected to the rest of your infrastructure.
 
 .. toctree::
-    :hidden:
     :maxdepth: 1
 
     Configure <configure>
     Integrate with COS <integrate-with-cos>
 
-Update and refresh
-------------------
+Maintenance and development
+---------------------------
 
-The following guides provide instructions on upgrading your deployment,
-including backup and restore processes.
+Upgrades, backups, and community contributions ensure the aproxy
+charm stays current, reliable, and benefits from ongoing improvements.
 
 .. toctree::
-    :hidden:
     :maxdepth: 1
 
     Back up and restore <back-up-restore>
     Upgrade <upgrade>
-
-Development
------------
-
-These guides can help you with contributing to the project.
-
-.. toctree::
-    :hidden:
-    :maxdepth: 1
-
     Contribute <contribute>

docs/index.md

@@ -67,7 +67,6 @@ Thinking about using the aproxy operator for your next project?
   1. [Actions](reference/actions.md)
   1. [Configurations](reference/configurations.md)
   1. [Integrations](reference/integrations.md)
-  1. [Metrics](reference/metrics.md)
   1. [Charm architecture](reference/charm-architecture.md)
 1. [Explanation](explanation)
   1. [Security](explanation/security.md)

docs/reference/charm-architecture.md

@@ -87,18 +87,6 @@ UpdateRelStyle(snap, upstream, $offsetY="-30", $offsetX="10")
 
 This subordinate charm does not use containers or Pebble-managed processes. Instead, it directly manages system resources (snap and nftables) on the host machine.
 
-## Metrics
-
-To be added in the future.
-
-<!--
-If the charm uses metrics, include a list under reference/metrics.md and link that document here.
-If the charm uses containers, you may include text here like:
-
-Inside the above mentioned containers, additional Pebble layers are defined in order to provide metrics.
-See [metrics](../explanation/link-to-metrics-document) for more information.
--->
-
 ## Juju events
 
 The charm observes the following Juju events:

docs/reference/index.rst

@@ -6,37 +6,37 @@
 Reference
 =========
 
-This section contains technical details and information about the aproxy charm.
-
-Charm usage
------------
-
-The following pages provide more information about the charm's features,
-including actions, configurations, and integrations.
+Technical specifications and architectural details for the aproxy charm serve
+as authoritative look-up material when configuring, integrating, or extending
+the charm.
 
 .. vale Canonical.013-Spell-out-numbers-below-10 = NO
 .. vale Canonical.500-Repeated-words = NO
 .. vale Canonical.004-Canonical-product-names = NO
 
+Configuration and operations
+----------------------------
+
+Operators control charm behavior through configuration options and Juju
+actions.
+
 .. toctree::
-    :hidden:
     :maxdepth: 1
 
     Actions <actions>
     Configurations <configurations>
-    Integrations <integrations>
-    Metrics <metrics>
 
 .. vale Canonical.004-Canonical-product-names = YES
 
-Architecture and deployments
-----------------------------
+Architecture and design
+-----------------------
 
-The following pages provide more details about the charm architecture and
-a high-level deployment with any required dependencies.
+The aproxy charm communicates with other applications through integrations.
+Understanding the charm architecture provides the structural context
+needed to see how those settings interact at runtime.
 
 .. toctree::
-    :hidden:
     :maxdepth: 1
 
     Charm architecture <charm-architecture>
+    Integrations <integrations>