patch: update documentation landing pages (6) (#282)

a-velasco · Mehdi-Bendriss · web-flow · commit be39f490f614 · 2026-04-09T14:08:05.000+02:00
## 🏷️ Type of changes   - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Tooling and CI - [ ] Dependencies upgrade or change - [ ] Chores / refactoring ## 📝 Description  This PR updates the home page and main Diataxis landing pages in accordance with the latest documentation standards. It solves [DPE-9652] and [DPE-9695]. ## 🧪 Manual testing steps    In the `docs` directory: ```shell make clean make install make run ``` ## 🔬 Automated testing steps     ## ✅ Checklist   - [ ] My code follows the code style of this project. - [x] I have added or updated any relevant documentation. - [x] I have read the [**CONTRIBUTING**](../blob/8/edge/CONTRIBUTING.md) document. - [ ] I have added tests to cover my changes. - [ ] All new and existing tests passed. [DPE-9652]: https://warthogs.atlassian.net/browse/DPE-9652?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ [DPE-9695]: https://warthogs.atlassian.net/browse/DPE-9695 --------- Signed-off-by: Andreia <andreia.velasco@canonical.com> Co-authored-by: Mehdi Bendriss <45567724+Mehdi-Bendriss@users.noreply.github.com>
diff --git a/docs/conf.py b/docs/conf.py
@@ -150,7 +150,7 @@
     #       it inherits the code license instead; specify it instead of 'CC-BY-SA'.
 
     "license": {
-        "name": "CC-BY-SA-3.0",
+        "name": "Apache License 2.0",
         "url": "https://github.com/canonical/mongo-single-kernel-library/blob/6/edge/LICENSE",
     },
 }
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -1,11 +1,25 @@
 (explanation)=
 # Explanation
 
+This section contains additional context about key concepts and the design behind Charmed MongoDB.
+
+## Architecture and design
+
+High-level implementation details of MongoDB concepts like sharding and users in the context of charms and Juju:
+
 ```{toctree}
 :titlesonly:
-
-Security <security/index>
 Sharding <sharding>
-Users <users>
+Internal users <users>
 Advanced statuses <advanced-statuses>
-```
+```
+
+## Security
+
+Overview of security measures in the charm and maintenance policies like security upgrades:
+
+```{toctree}
+:titlesonly:
+
+Security <security/index>
+```
diff --git a/docs/explanation/security/hardening-guide.md b/docs/explanation/security/hardening-guide.md
@@ -132,15 +132,15 @@ A new version of the Charmed MongoDB image may be released to provide patching o
 Charmed MongoDB and Charmed Mongos install pinned revisions of the [Charmed MongoDB snap](https://snapcraft.io/charmed-mongodb), to provide reproducible and secure environments. 
 New versions of Charmed MongoDB and Charmed Mongos may be released to provide patching of vulnerabilities (CVEs). 
 It is important to refresh the charms regularly to make sure the workload is as secure as possible. 
-For more information on how to refresh the MongoDB charm, see {ref}`how-to-upgrade`.
+For more information on how to refresh the MongoDB charm, see {ref}`upgrade`.
 ```
 ```{tab-item} K8s
 :sync: k8s
 
 Charmed MongoDB K8s and Charmed Mongos K8s install a pinned revisions of the [Charmed MongoDB snap](https://snapcraft.io/charmed-mongodb), to provide reproducible and secure environments. 
 New versions of Charmed MongoDB K8s and Charmed Mongos K8s may be released to provide patching of vulnerabilities (CVEs). 
 It is important to refresh charms regularly to make sure the workload is as secure as possible. 
-For more information on how to refresh the MongoDB charm, see {ref}`how-to-upgrade`.
+For more information on how to refresh the MongoDB charm, see {ref}`upgrade`.
 ```
 ````
 
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -1,16 +1,80 @@
-(how-to-guides)=
+(how-to)=
 # How-to guides
 
+Key processes and common tasks for deploying, configuring, and operating Charmed MongoDB.
+
+## Deployment and setup
+
+Available deployment methods and operations to consider at deploy-time:
+
 ```{toctree}
 :titlesonly:
+:maxdepth: 2
 
 Deploy <deploy/index>
+````
+
+## Operations and maintenance
+
+Essential operations to configure and manage a MongoDB cluster:
+
+```{toctree}
+:titlesonly:
+
 Scale replicas and shards <scale-replicas-and-shards>
-Enable TLS <enable-tls>
+Enable TLS encryption <enable-tls>
+````
+
+Connect to an application and manage user credentials and authentication:
+
+```{toctree}
+:titlesonly:
+
 Manage client connections <manage-client-connections>
 Enable LDAP <enable-ldap>
-Decommission your deployment <decommission>
-Monitoring <monitoring/index>
+````
+
+### Back up and restore
+
+Configure storage providers and manage backups for safety and data migration:
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
 Back up and restore <back-up-and-restore/index>
+```
+
+### Monitoring
+
+Integrate with observability services like Grafana through the Canonical Observability Stack (COS):
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Monitoring <monitoring/index>
+```
+
+### Upgrade
+
+Upgrade your MongoDB applications to a new minor revision in-place, or across major versions:
+
+```{toctree}
+:titlesonly:
+:maxdepth: 3
+
 Upgrade <upgrade/index>
-```
+```
+
+## Delete your deployment
+
+Securely decomission your deployment to avoid exposing sensitive data:
+
+```{toctree}
+:titlesonly:
+
+Decommission your deployment <decommission>
+```
+
+For more information about security hardening, see {ref}`security`.
diff --git a/docs/how-to/monitoring/index.md b/docs/how-to/monitoring/index.md
@@ -1,3 +1,4 @@
+(monitoring)=
 # Monitoring
 
 ```{toctree}
diff --git a/docs/how-to/upgrade/index.md b/docs/how-to/upgrade/index.md
@@ -1,17 +1,18 @@
-(how-to-upgrade)=
+(upgrade)=
 # How to upgrade
 
-The MongoDB charm supports two kinds of upgrades:
-* Minor in-place upgrades of MongoDB 6 revisions via [`juju refresh`](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/refresh/#details)
-  * See: {ref}`minor-version-upgrade`
-* Major upgrade from MongoDB 6 to MongoDB 8 via cluster migration
-  * See: {ref}`major-version-upgrade`
-
+Minor in-place upgrades of MongoDB 6 revisions via [`juju refresh`](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/refresh/#details):
 
 ```{toctree}
 :titlesonly:
-:hidden:
 
 Minor version upgrade <minor-version-upgrade/index>
+```
+
+Major upgrade from MongoDB 6 to MongoDB 8 via cluster migration:
+
+```{toctree}
+:titlesonly:
+
 Major version upgrade <major-version-upgrade>
 ```
diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,10 @@
+---
+relatedlinks: "[Charmhub&#32;|&#32;MongoDB&#32;VM](https://charmhub.io/mongodb?channel=6/edge), [Charmhub&#32;|&#32;MongoDB&#32;K8s](https://charmhub.io/mongodb-k8s?channel=6/edge)"
+myst:
+  html_meta:
+    description: "Official documentation for Charmed MongoDB. Deploy and manage MongoDB on bare metal/virtual machines and Kubernetes using Juju."
+---
+
 # Charmed MongoDB documentation
 
 Charmed MongoDB is an open-source software operator that deploys and operates [MongoDB](https://www.mongodb.com/) databases on IAAS/VM and Kubernetes. In addition to MongoDB's essential operations for managing production-grade deployments, Charmed MongoDB offers advanced features such as backup and restores, monitoring, easy application integrations, sharding, and encryption.
@@ -8,33 +15,60 @@ This charm is for anyone looking for a complete database management interface. T
 
 ## In this documentation
 
-|  |  |
-|--|--|
-| {ref}`tutorial` </br> A hands-on introduction to using the Charmed MongoDB operator for new users </br> |  {ref}`how-to-guides` </br> Step-by-step guides covering key operations and common tasks |
-| {ref}`reference` </br> Technical information - requirements, release notes | {ref}`explanation` </br> Clarification of key topics  |
+This documentation contains practical information about installing and operating Charmed MongoDB. It covers instructions for both VM and K8s substrates.  
+
+### Get started
+
+Learn about what's in the charm, how to try it out, and perform the most common operations.
+
+* **Charm overview**: {ref}`system-requirements` • {ref}`release-notes` 
+* **Deploy MongoDB**: {ref}`Quickstart <via-juju-cli>` • {ref}`Guided tutorial <tutorial>` • {ref}`Terraform <via-terraform>`
+* **Key operations**: {ref}`Scale your cluster <scale-replicas-and-shards>` • {ref}`Connect to a client <manage-client-connections>` • {ref}`Create a backup <create-a-backup>`
+
+### Production deployments
+
+Advanced deployments and operations focused on production scenarios and high availability.
+
+* **Advanced configuration**: {ref}`Enable LDAP <enable-ldap>`
+* **Upgrades and data migration**: {ref}`Minor upgrades <minor-version-upgrade>` • {ref}`Upgrade from MongoDB 6 to 8 <major-version-upgrade>` • {ref}`Migrate a cluster <migrate-a-cluster>`
+* **Security**: {ref}`TLS encryption <enable-tls>` • {ref}`Hardening guide <hardening-guide>`
+* **Troubleshooting**: {ref}`Monitoring <monitoring>` • {ref}`Advanced statuses <advanced-statuses>` 
+
+### Charm developers
+
+Information for developers looking to make their application compatible with MongoDB.
+
+* **Libraries and interfaces**: [`mongodb_client` interface](https://charmhub.io/integrations/mongodb_client)
+* **Learn more about the charm**: {ref}`Internal users <users>` • {ref}`sharding`
+
+## How this documentation is organised
+
+This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/):
+
+* The {ref}`tutorial` provides step-by-step guidance for a beginner through the basics of a deployment in a local machine.
+* {ref}`how-to` are more focused, and assume you already have basic familiarity with the product.
+* {ref}`reference` contains structured information for quick lookup, such as system requirements and configuration parameters
+* {ref}`explanation` gives more background and context about key topics
 
 ## Project and community
 
 Charmed MongoDB is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
 
-* Check our [Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct)
-* Raise software issues or feature requests in [GitHub](https://github.com/canonical/mongo-single-kernel-library/issues)
-<!-- * Report security issues through [LaunchPad](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File).  -->
-* Meet the community and chat with us on [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com)
-* [Contribute](https://github.com/canonical/mongo-single-kernel-library/blob/6/edge/CONTRIBUTING.md)
-
-## Licensing & trademark
+### Get involved
 
-The Charmed MongoDB Operator is free software, distributed under the [Apache Software License, version 2.0](https://github.com/canonical/mongo-single-kernel-library/blob/6/edge/LICENSE). It installs, operates, and depends on [MongoDB Community Version](https://github.com/mongodb/mongo), which is licensed under the Server Side Public License (SSPL)
+* [Report an issue](https://github.com/canonical/mongo-single-kernel-library/issues/new/choose)
+* [Public Matrix channel](https://matrix.to/#/#charmhub-data-platform:ubuntu.com)
+* [Discourse forum](https://discourse.charmhub.io/tag/mongodb)
+* [Contribute](https://github.com/canonical/mongo-single-kernel-library/blob/6/edge/CONTRIBUTING.md)
 
-MongoDB is a trademark or registered trademark of MongoDB, Inc. Other trademarks are property of their respective owners.
+### Governance and policies
 
+* [Code of Conduct](https://ubuntu.com/community/code-of-conduct)
 
 ```{toctree}
 :titlesonly:
 :hidden:
 
-Home <self>
 Tutorial <tutorial>
 How-to guides <how-to/index>
 Reference <reference/index>
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -1,12 +1,20 @@
 (reference)=
 # Reference
 
-This section contains technical specifications, APIs, release notes, and other reference material for fast lookup.
+Release notes for each stable revision of Charmed MongoDB 6 on VM and K8s:
 
 ```{toctree}
 :titlesonly:
+:maxdepth: 3
 
 Release notes <release-notes/index>
+```
+
+Software and hardware requirements and other technical reference material:
+
+```{toctree}
+:titlesonly:
+
 System requirements <system-requirements>
 Charm testing <charm-testing>
 ```

Original file line number	Diff line number	Diff line change
`@@ -150,7 +150,7 @@`
`150`	`150`	`# it inherits the code license instead; specify it instead of 'CC-BY-SA'.`
`151`	`151`
`152`	`152`	`"license": {`
`153`		`- "name": "CC-BY-SA-3.0",`
	`153`	`+ "name": "Apache License 2.0",`
`154`	`154`	`"url": "https://github.com/canonical/mongo-single-kernel-library/blob/6/edge/LICENSE",`
`155`	`155`	`},`
`156`	`156`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+(monitoring)=`
`1`	`2`	`# Monitoring`
`2`	`3`
`3`	`4`	```{toctree}