docs: Implement new home page pattern and address feedback

docs/changelog.md

@@ -12,6 +12,11 @@ Each revision is versioned by the date of the revision.
 
 - Added relation endpoints reference page.
 
+## 2026-05-25
+
+- docs: Updated the home page to implement the new pattern for the "In this documentation" section.
+- docs: Reorganized two tutorials to how-to section; expanded the upgrade guide
+
 ## 2026-04-17
 
 - Added missing settings from haproxy-route-tcp relation template.

docs/conf.py

@@ -232,6 +232,8 @@
     'reference/style-guide-myst/': '../myst-syntax-reference',
     'reference/style-guide/': '../rst-syntax-reference',
     './getting-started': './tutorial/getting-started',
+    'tutorial/loadbalancing-for-a-grpc-server': '/how-to/loadbalancing-for-a-grpc-server',
+    'tutorial/loadbalancing-for-an-ftp-server': '/how-to/loadbalancing-for-an-ftp-server',
 }
 
 

docs/how-to/index.md

@@ -8,45 +8,51 @@ myst:
 
 # How-to guides
 
-The following guides cover key processes and common tasks for managing and using the HAProxy charm.
+Manage the full operations lifecycle of the HAProxy charm, from initial deployment through
+production maintenance. Each guide assumes that you’ve already deployed the charm with Juju.
 
 ## Common use-cases
 
 Once you've set up the HAProxy charm, you can take advantage of the built-in features and capabilities to customize the charm based on your specific needs and use case.
 
 ```{toctree}
 :maxdepth: 1
+Configure high availability <configure-high-availability.md>
 Integrate with non-charm workloads <integrate-with-non-charm-workload.md>
 Provide extra configurations for ingress requirer charms <provide-extra-configurations-for-ingress-requirer-charms.md>
-Protect a hostname using OpenID Connect <protect-hostname-spoe-auth.md>
-Enable DDoS Protection <enable-ddos-protection.md>
 Control haproxy-route relation data <control-haproxy-route-relation-data.md>
-Configure high availability <configure-high-availability.md>
+Configure virtual IP on OpenStack <configure-virtual-ip-on-openstack.md>
 ```
 
-## Platform-specific workflows
+## Load balancing
 
-In some cases additional steps need to be performed on specific substrates to ensure that the charm is working as intended.
+Additional steps need to be performed to provide load balancing to your deployment
+depending on your required server protocol.
 
 ```{toctree}
 :maxdepth: 1
-Configure virtual IP on OpenStack <configure-virtual-ip-on-openstack.md>
+Provide load balancing for a gRPC server <loadbalancing-for-a-grpc-server.md>
+Provide load balancing for an FTP server <loadbalancing-for-an-ftp-server.md>
 ```
 
-## Maintenance
+## Security
 
-This section contains how-to guides for maintenance actions that you might need to take while operating the charm.
+The HAProxy charm comes with built-in configurations and integrations to secure your deployment
+against vulnerabilities and attacks.
 
 ```{toctree}
 :maxdepth: 1
-Upgrade <upgrade.md>
+Enable DDoS Protection <enable-ddos-protection.md>
+Protect a hostname using OpenID Connect <protect-hostname-spoe-auth.md>
 ```
 
-## Development
+## Maintenance and development
 
-This section contains how-to guides for developing the charm.
+Upgrades and community contributions ensure the HAProxy charm stays current
+and benefits from ongoing improvements.
 
 ```{toctree}
 :maxdepth: 1
+Upgrade <upgrade.md>
 Contribute <contribute.md>
 ```

docs/tutorial/loadbalancing-for-a-grpc-server.md → docs/how-to/loadbalancing-for-a-grpc-server.md

@@ -1,53 +1,30 @@
-(tutorial_loadbalancing_for_a_grpc_server)=
+(how_to_loadbalancing_for_a_grpc_server)=
 
-# Loadbalancing for a gRPC server
+# How to provide load balancing for a gRPC server
 
-In this tutorial we'll look at how to deploy the HAProxy charm to provide load balancing for a VM running [`flagd`](https://flagd.dev). This tutorial is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms.
+In this guide we'll look at how to deploy the HAProxy charm to provide load balancing for a VM running [`flagd`](https://flagd.dev). This guide is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms.
 
 ## Requirements
 
 You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station
 should have at least 4 CPU cores, 8 GB of RAM, and 50 GB of disk space.
 
-````{tip}
-You can use Multipass to create an isolated environment by running:
-```
-multipass launch 24.04 --name charm-tutorial-vm --cpus 4 --memory 8G --disk 50G
-```
-````
-
-This tutorial requires the following software to be installed on your working station
+This guide requires the following software to be installed on your working station
 (either locally or in the Multipass VM):
 
 - Juju 3.3
 - LXD 5.21.4
 
-Use [Concierge](https://github.com/canonical/concierge) to set up Juju and LXD:
-
-```
-sudo snap install --classic concierge
-sudo concierge prepare -p machine
-```
+For this guide, Juju must be bootstrapped to a LXD controller. 
 
-This first command installs Concierge, and the second command uses Concierge to install
-and configure Juju and LXD.
+Follow the {ref}`setup instructions <tutorial_requirements>` in the tutorial to achieve these requirements.
 
-For this tutorial, Juju must be bootstrapped to a LXD controller. Concierge should
-complete this step for you, and you can verify by checking for `msg="Bootstrapped Juju" provider=lxd`
-in the terminal output and by running `juju controllers`.
+## Set up a Juju model
 
-If Concierge did not perform the bootstrap, run:
+To manage resources effectively and to separate this guide's workload from your usual work, create a new model using the following command:
 
-```bash
-juju bootstrap lxd tutorial-controller
 ```
-
-## Set up a tutorial model
-
-To manage resources effectively and to separate this tutorial's workload from your usual work, create a new model using the following command:
-
-```
-juju add-model haproxy-tutorial
+juju add-model haproxy-guide
 ```
 
 ## Deploy the HAProxy charm
@@ -184,12 +161,3 @@ After running the command you should see the reply from `flagd`:
 }
 ```
 
-## Clean up the environment
-
-Well done! You've successfully completed this tutorial.
-
-To remove the model environment you created, use the following command:
-
-```
-juju destroy-model haproxy-tutorial
-```

docs/tutorial/loadbalancing-for-an-ftp-server.md → docs/how-to/loadbalancing-for-an-ftp-server.md

@@ -1,53 +1,30 @@
-(tutorial_loadbalancing_for_an_ftp_server)=
+(how_to_loadbalancing_for_an_ftp_server)=
 
-# Loadbalancing for an FTP server
+# How to provide load balancing for an FTP server
 
-In this tutorial we'll look at how to deploy the HAProxy charm to provide TCP load balancing for a VM running an FTP server. This tutorial is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms.
+In this guide we'll look at how to deploy the HAProxy charm to provide TCP load balancing for a VM running an FTP server. This guide is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms.
 
 ## Requirements
 
 You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station
 should have at least 4 CPU cores, 8 GB of RAM, and 50 GB of disk space.
 
-````{tip}
-You can use Multipass to create an isolated environment by running:
-```
-multipass launch 24.04 --name charm-tutorial-vm --cpus 4 --memory 8G --disk 50G
-```
-````
-
-This tutorial requires the following software to be installed on your working station
+This guide requires the following software to be installed on your working station
 (either locally or in the Multipass VM):
 
 - Juju 3.3
 - LXD 5.21.4
 
-Use [Concierge](https://github.com/canonical/concierge) to set up Juju and LXD:
-
-```
-sudo snap install --classic concierge
-sudo concierge prepare -p machine
-```
+For this guide, Juju must be bootstrapped to a LXD controller. 
 
-This first command installs Concierge, and the second command uses Concierge to install
-and configure Juju and LXD.
+Follow the {ref}`setup instructions <tutorial_requirements>` in the tutorial to achieve these requirements.
 
-For this tutorial, Juju must be bootstrapped to a LXD controller. Concierge should
-complete this step for you, and you can verify by checking for `msg="Bootstrapped Juju" provider=lxd`
-in the terminal output and by running `juju controllers`.
+## Set up a Juju model
 
-If Concierge did not perform the bootstrap, run:
+To manage resources effectively and to separate this guide's workload from your usual work, create a new model using the following command:
 
-```bash
-juju bootstrap lxd tutorial-controller
 ```
-
-## Set up a tutorial model
-
-To manage resources effectively and to separate this tutorial's workload from your usual work, create a new model using the following command:
-
-```
-juju add-model haproxy-tutorial
+juju add-model haproxy-guide
 ```
 
 ## Deploy the HAProxy charm
@@ -132,12 +109,3 @@ Using binary mode to transfer files.
 ftp>
 ```
 
-## Clean up the environment
-
-Well done! You've successfully completed this tutorial.
-
-To remove the model environment you created, use the following command:
-
-```
-juju destroy-model haproxy-tutorial
-```

docs/how-to/upgrade.md

@@ -2,8 +2,17 @@
 
 # How to upgrade
 
-Upgrade the charm with the `juju refresh` command:
+Upgrade the charm with the `juju refresh` command.
+For example, to upgrade `haproxy` along the `2.8/edge` channel, use:
 
 ```bash
-juju refresh <haproxy-operator> --channel=2.8/edge
+juju refresh haproxy --channel=2.8/edge
 ```
+
+The charm is stateless, so you don't need to perform a data backup
+before upgrading.
+
+Breaking changes aren't introduced in subsequent revisions in a given `channel`.
+As long as you upgrade using the same `channel`, all configurations and
+relations should remain intact between `haproxy` and the other charms
+in your deployment.

docs/index.md

@@ -5,34 +5,51 @@ myst:
 ---
 # HAProxy operator
 
-The HAProxy operator is an open-source software operator that deploys and operates HAProxy IAAS/VM that functions on Juju 3.3 and above. The charm offers advanced features such as TLS, monitoring and high-availability. This operator is built for **IAAS/VM** and is not supported in **Kubernetes** environments.
+The HAProxy operator is an open-source software operator that deploys and operates HAProxy on Juju 3.3 and above.
+
+The charm provides a managed ingress entry point for backend applications, handling secure traffic routing and load balancing. It also offers advanced features such as TLS, monitoring and high-availability.
+
+This operator is built for **IaaS/VM** and is not supported in **Kubernetes** environments.
 
 ## In this documentation
 
-| | |
-|--|--|
-|  {ref}`Tutorial <tutorial_index>`</br>  Get started - a hands-on introduction to using the charm for new users </br> |  {ref}`How-to guides <how_to_index>` </br> Step-by-step guides covering key operations and common tasks |
-| {ref}`Reference <reference_index>` </br> Technical information - specifications, APIs, architecture | {ref}`Explanation <explanation_index>` </br> Concepts - discussion and clarification of key topics  |
+```{list-table}
+   :header-rows: 1
+   :widths: 10 25
 
-## Contributing to this documentation
+* - 
+  - 
+* - **Get started**
+  - {ref}`tutorial_getting_started`
+* - **Deployment**
+  - {ref}`Configure high availability <how_to_configure_high_availability>` | {ref}`Control backend routing <how_to_control_haproxy_route_relation_data>` | {ref}`Create OpenStack virtual IP <how_to_configure_virtual_ip_on_openstack>`
+* - **Integrations**
+  - {ref}`Relation endpoints <reference_relation_endpoints>` | {ref}`Integrate with non-charmed workloads <how_to_integrate_with_non_charm_workload>` | {ref}`Configure ingress requirers <how_to_provide_extra_configurations_for_ingress_requirer_charms>`
+* - **Supported protocols** 
+  - {ref}`FTP <how_to_loadbalancing_for_an_ftp_server>` | {ref}`gRPC <how_to_loadbalancing_for_a_grpc_server>` | {ref}`HTTP/2 <reference_http2_support>`
+* - **Security**
+  - {ref}`Overview <explanation_security>` | {ref}`Enable DDoS protection <how_to_enable_ddos_protection>` | {ref}`Protect a hostname <how_to_protect_hostname_spoe_auth>`
+```
 
-Documentation is an important part of this project, and we take the same open-source approach
-to the documentation as the code. As such, we welcome community contributions, suggestions, and
-constructive feedback on our documentation.
-See {ref}`how_to_contribute` for more information.
+## How this documentation is organized
 
+This documentation uses the
+[Diátaxis documentation structure](https://diataxis.fr/).
 
-If there's a particular area of documentation that you'd like to see that's missing, please 
-[file a bug](https://github.com/canonical/haproxy-operator/issues).
+* The {ref}`Tutorial <tutorial_index>` takes you step-by-step through a basic deployment of the HAProxy charm.
+* The {ref}`How-to guides <how_to_index>` cover practical tasks for configuring, integrating, and maintaining your HAProxy deployment.
+* {ref}`Reference <reference_index>` provides technical details on supported server protocols and authentication.
+* {ref}`Explanation <explanation_index>` includes context and overviews on security and high availability.
 
 ## Project and community
 
 The HAProxy operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community 
 projects, contributions, suggestions, fixes, and constructive feedback.
 
-- [Code of conduct](https://ubuntu.com/community/code-of-conduct)
-- [Get support](https://discourse.charmhub.io/)
-- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+- [Code of conduct](https://ubuntu.com/community/docs/ethos/code-of-conduct)
+- [File a bug](https://github.com/canonical/haproxy-operator/issues)
+- Get support through the [Discourse forum](https://discourse.charmhub.io/)
+- Join our [online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
 - {ref}`Contribute <how_to_contribute>`
 
 Thinking about using the HAProxy operator for your next project? 
@@ -45,5 +62,10 @@ Tutorial <tutorial/index.md>
 How-to guides <how-to/index.md>
 Reference <reference/index.md>
 Explanation <explanation/index.md>
+```
+
+```{toctree}
+:hidden:
+:maxdepth: 1
 Release notes <release-notes/index.md>
 ```

docs/reference/index.md

@@ -15,6 +15,6 @@ The pages in this section contain technical information for topics relevant to t
 grpc-support.md
 http2-support.md
 relation-endpoints.md
-spoe-auth-support.md
+SPOE authentication <spoe-auth-support.md>
 Changelog <../changelog.md>
 ```

docs/tutorial/getting-started.md

@@ -4,6 +4,8 @@
 
 In this tutorial we'll deploy the HAProxy charm to provide ingress to a backend application, then configure high-avalability using the `hacluster` relation. This tutorial is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms.
 
+(tutorial_requirements)=
+
 ## Requirements
 
 You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station
@@ -136,13 +138,21 @@ Well done! You've successfully completed the HAProxy tutorial.
 
 To remove the model environment you created, use the following command:
 
+<!-- SPREAD SKIP -->
+
 ```
 juju destroy-model haproxy-tutorial --no-prompt
 ```
 
+<!-- SPREAD SKIP END -->
+
+<!-- SPREAD
+juju destroy-model haproxy-tutorial --no-prompt --force
+-->
+
 ## Next steps
 
-Check out these advanced tutorials to learn how to use HAProxy to provide load balancing for different protocols.
+Check out these advanced guides to learn how to use HAProxy to provide load balancing for different protocols.
 
-* {ref}`tutorial_loadbalancing_for_an_ftp_server`
-* {ref}`tutorial_loadbalancing_for_a_grpc_server`
+* {ref}`how_to_loadbalancing_for_an_ftp_server`
+* {ref}`how_to_loadbalancing_for_a_grpc_server`

docs/tutorial/index.md

@@ -17,16 +17,6 @@ This tutorial walks through the deployment of the HAProxy charm to provide HTTP
 ```{toctree}
 :glob:
 :titlesonly:
-Getting Started <getting-started.md>
+Basic HAProxy deployment <getting-started.md>
 ```
 
-## Protocol-specific setup
-
-In these tutorials you will learn how to use HAProxy to provide load balancing for different protocols.
-
-```{toctree}
-:glob:
-:titlesonly:
-Loadbalancing for an FTP server <loadbalancing-for-an-ftp-server.md>
-Loadbalancing for a gRPC server <loadbalancing-for-a-grpc-server.md>
-```