Merge pull request #264 from canonical/af-tweaks

docs: tweaks to navigation headings
canonical · Sep 10, 2024 · 56090e9 · 56090e9
2 parents 9f32fb6 + 082b161
commit 56090e9
Show file tree

Hide file tree

Showing 5 changed files with 21 additions and 29 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -2,16 +2,17 @@
 
 .. _home:
 
-Charmed MLflow Documentation
+Charmed MLflow documentation
 ============================
 
-Charmed MLflow is a platform for managing the end-to-end machine learning lifecycle.
+Charmed MLflow is a platform for managing the end-to-end Machine Learning (ML) lifecycle.
 
-It provides tools for tracking experiments, packaging code into reproducible runs, and sharing and deploying models. It integrates with popular machine learning frameworks.
+It provides tools for tracking experiments, packaging code into reproducible runs, and sharing and deploying models. 
+It integrates with popular ML frameworks.
 
-It addresses a number of common machine learning challenges: collaboration, reproducibility, maintenance, organisation and scaling.
+It also addresses a number of common ML challenges including collaboration, reproducibility, maintenance, organisation and scaling.
 
-It's ideal for data scientists, ML engineers, hobbyists and teams looking to optimise their ML workflows with charms.
+It is intended for data scientists and ML engineers, looking to optimise their ML workflows with charms.
 
 ---------
 
@@ -29,11 +30,6 @@ In this documentation
       **Step-by-step guides** covering key operations and common tasks in Charmed MLflow
 
 .. grid:: 1 1 2 2
-   :reverse:
-
-   .. grid-item:: :doc:`Reference <reference/index>`
-
-      **Technical information** - specifications, APIs, architecture of Charmed MLflow
 
    .. grid-item:: :doc:`Explanation <explanation/index>`
 
@@ -46,18 +42,18 @@ Project and community
 
 Charmed MLflow is an open-source project that values its community. We warmly welcome contributions, suggestions, fixes, and constructive feedback from everyone.
 
-* `Code of conduct`_
-* `Contribute`_
-* `Join our online chat`_
-* `Upstream Project`_
-* `Discourse Forum`_
+* Read our `Code of conduct`_.
+* `Contribute`_ and `report bugs <https://github.com/canonical/mlflow-operator/issues/new/choose>`_.
+* Join the `Discourse forum`_.
+* `Talk to us`_.
+* Learn more about the `upstream project`_.
 
 .. toctree::
    :hidden:
    :maxdepth: 2
 
+   Home <self>
    tutorial/index
-   how-to/index
-   reference/index
+   How to <how-to/index>
    explanation/index
-   contributing
+   Contribute <contributing>
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt
@@ -4,14 +4,14 @@
 .. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/
 
 .. _Code of conduct: https://ubuntu.com/community/ethos/code-of-conduct
-.. _Join our online chat: https://chat.charmhub.io/charmhub/channels/charmed-mlops
+.. _Talk to us: https://chat.charmhub.io/charmhub/channels/charmed-mlops
 .. _Contribute: https://github.com/canonical/mlflow-operator/blob/main/CONTRIBUTING.md
-.. _Upstream Project: https://mlflow.org/
-.. _Discourse Forum: https://discourse.charmhub.io/tag/mlflow
+.. _Upstream project: https://mlflow.org/
+.. _Discourse forum: https://discourse.charmhub.io/tag/mlflow
 .. _rclone: https://snapcraft.io/rclone
 .. _configured: https://rclone.org/s3/#configuration
 .. _yq binary: https://snapcraft.io/yq
-.. _Create a backup: https://charmhub.io/mysql-k8s/docs/h-create-and-list-backups
+.. _Create a backup: https://charmhub.io/mysql-k8s/docs/h-create-backup
 
 .. _MicroK8s: https://microk8s.io/
 

diff --git a/docs/tutorial/mlflow-kubeflow.rst b/docs/tutorial/mlflow-kubeflow.rst
@@ -1,5 +1,5 @@
-Getting Started with Charmed MLflow and Kubeflow
-================================================
+Get started with Charmed MLflow and Kubeflow
+============================================
 
 +-----------+---------+
 | Component | Version |

diff --git a/docs/tutorial/mlflow.rst b/docs/tutorial/mlflow.rst
@@ -1,4 +1,4 @@
-Get Started with Charmed MLflow
+Get started with Charmed MLflow
 ==================================
 
 +-----------+---------+