canonical · a-velasco · Oct 29, 2025 · Oct 28, 2025 · Oct 28, 2025 · Oct 28, 2025
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -1,56 +1,49 @@
 # Explanation
 
-Additional context about key concepts behind the PostgreSQL charm, including design and legacy information.
+Additional context about the PostgreSQL charm, including design, legacy information, and security.
 
-## Core concepts and design
-* [Architecture]
-* [Interfaces and endpoints]
-* [Juju]
-* [Legacy charm]
-
-## Operational concepts
-* [Users]
-* [Logs]
-* [Connection pooling]
-
-## Security and hardening
-* [Security hardening guide][Security]
-  * [Cryptography]
-
-## Development
-Charm event flowcharts:
-* [Charm]
-* [Relations]
-* [Backups]
-
-<!-- Links -->
-
-[Architecture]: /explanation/architecture
-[Interfaces and endpoints]: /explanation/interfaces-and-endpoints
-[Users]: /explanation/users
-[Logs]: /explanation/logs
-[Juju]: /explanation/juju
-[Legacy charm]: /explanation/legacy-charm
-[Connection pooling]: /explanation/connection-pooling
-[Charm]: /explanation/flowcharts/charm
-[Relations]: /explanation/flowcharts/relations
-[Backups]: /explanation/flowcharts/backups
-[Security]: /explanation/security/index
-[Cryptography]: /explanation/security/cryptography
+## Core
 
+Core concepts about the history and design of the charm:
 
 ```{toctree}
 :titlesonly:
-:maxdepth: 2
-:glob:
-:hidden:
 
 Architecture <architecture>
 Interfaces and endpoints <interfaces-and-endpoints>
-Juju <juju>
 Legacy charm <legacy-charm>
+Juju <juju>
+```
+
+## Operation
+
+Clarification of standard operational concepts:
+
+```{toctree}
+:titlesonly:
+
 Users <users>
 Logs <logs>
 Connection pooling <connection-pooling>
+```
+
+## Security
+
+Security hardening overview:
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
 Security <security/index>
-Flowcharts <flowcharts/index>
+```
+
+## Development
+
+Charm event flowcharts:
+
+```{toctree}
+:titlesonly:
+
+Flowcharts <flowcharts/index>
+```
diff --git a/docs/how-to/deploy/index.md b/docs/how-to/deploy/index.md
@@ -1,82 +1,67 @@
+(deploy)=
 # How to deploy
 
-This page introduces the PostgreSQL deployment process and lists all related guides.
+The basic requirements for deploying a charm are the [**Juju client**](https://documentation.ubuntu.com/juju/3.6/) and a machine [**cloud**](https://juju.is/docs/juju/cloud).
 
-## General deployment instructions
+For more details, see {ref}`system-requirements`.
 
-The basic requirements for deploying a charm are the [**Juju client**](https://juju.is/docs/juju) and a machine [**cloud**](https://juju.is/docs/juju/cloud).
+If you are not sure where to start, or would like a more guided walkthrough for setting up your environment, see the {ref}`tutorial`.
 
-First, [bootstrap](https://juju.is/docs/juju/juju-bootstrap) the cloud controller and create a [model](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/model/): 
-```text
+## Quickstart
+
+First, [bootstrap](https://juju.is/docs/juju/juju-bootstrap) the cloud controller and create a [model](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/model/):
+
+```shell
 juju bootstrap <cloud name> <controller name>
 juju add-model <model name>
 ```
 
-Then, either continue with the `juju` client **or** use the `terraform juju` client to deploy the PostgreSQL charm.
+Then, use the [`juju deploy`](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/juju-cli/list-of-juju-cli-commands/deploy/) command:
 
-**To deploy with the `juju` client:**
-```text
-juju deploy postgresql-k8s --channel 16/stable --trust
+```shell
+juju deploy postgresql-k8s --channel 16/edge -n <number_of_replicas> --trust
 ```
-> See also: [`juju deploy` command](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/juju-cli/list-of-juju-cli-commands/deploy/)
-
-**To deploy with `terraform juju`**, follow the guide [How to deploy using Terraform].
-> See also: [Terraform Provider for Juju documentation](https://canonical-terraform-provider-juju.readthedocs-hosted.com/latest/)
 
-If you are not sure where to start or would like a more guided walkthrough for setting up your environment, see the [](/tutorial/index).
+If you are not sure where to start or would like a more guided walkthrough for setting up your environment, see the {ref}`tutorial`.
 
+(deploy-clouds)=
 ## Clouds
 
-How to bootstrap and configure different cloud services:
-* [Canonical K8s]
-* [Google Kubernetes Engine]
-* [Amazon Elastic Kubernetes Service]
-* [Azure Kubernetes Service]
-* [How to deploy on multiple availability zones (AZ)]
-
-## Networking
-
-* [How to enable TLS]
-* [How to connect from outside the local network]
-
-## Airgapped
+Set up different cloud services for a Charmed PostgreSQL deployment:
 
-[How to deploy in an offline or air-gapped environment] goes over the special configuration steps for installing PostgreSQL in an airgapped environment via Charmhub and the Snap Store Proxy.
+```{toctree}
+:titlesonly:
 
-## Cluster-cluster replication
+Canonical K8s <canonical-k8s>
+GKE <gke>
+EKS <eks>
+AKS <aks>
+```
 
-Cluster-cluster, cross-regional, or multi-server asynchronous replication focuses on disaster recovery by distributing data across different servers. 
+Deploy a cluster on a cloud using different availability zones:
 
-The [Cross-regional async replication] guide goes through the steps to set up clusters for cluster-cluster replication, integrate with a client, and remove or recover a failed cluster.
+```{toctree}
+:titlesonly:
 
-[Tutorial]: /tutorial/index
+Multi-AZ <multi-az>
+```
 
-[How to deploy using Terraform]: /how-to/deploy/terraform
+## Terraform
 
-[Canonical K8s]: /how-to/deploy/canonical-k8s
-[Google Kubernetes Engine]: /how-to/deploy/gke
-[Amazon Elastic Kubernetes Service]: /how-to/deploy/eks
-[Azure Kubernetes Service]: /how-to/deploy/aks
+Deploy PostgreSQL and automate your infrastructure with the Juju Terraform Provider:
 
-[How to deploy on multiple availability zones (AZ)]: /how-to/deploy/multi-az
+```{toctree}
+:titlesonly:
 
-[How to enable TLS]: /how-to/enable-tls
-[How to connect from outside the local network]: /how-to/external-network-access
+Terraform <terraform>
+```
 
-[How to deploy in an offline or air-gapped environment]: /how-to/deploy/air-gapped
-[Cross-regional async replication]: /how-to/cross-regional-async-replication/index
+## Airgapped
 
+Install PostgreSQL in an airgapped environment via Charmhub and the Snap Store Proxy:
 
 ```{toctree}
 :titlesonly:
-:maxdepth: 2
-:glob:
-:hidden:
 
-Canonical K8s <canonical-k8s>
-Google Kubernetes Engine <gke>
-Amazon Elastic Kubernetes Service <eks>
-Azure Kubernetes Service <aks>
-Multi-AZ <multi-az>
-Terraform <terraform>
 Air-gapped <air-gapped>
+```
diff --git a/docs/how-to/deploy/terraform.md b/docs/how-to/deploy/terraform.md
@@ -12,7 +12,7 @@ Storage support was added in [Juju Terraform Provider version 0.13+](https://git
 
 ## Install Terraform tooling
 
-This guide assumes Juju is installed and you have a K8s controller already bootstrapped. For more information, check the [](/tutorial/index).
+This guide assumes Juju is installed and you have a K8s controller already bootstrapped. For more information, check the {ref}`tutorial`.
 
 Let's install Terraform Provider and example modules: