Update docs (#196)

* Update index.md (ISD-2291)

Adopt template landing page:
- Removed jargon from overview section
- Added "In this documentation" and "Contributing to this documentation" sections
- Updated links

* Update contents (ISD-2323)

- Added missing documents to how-to section
- Verified all the titles follow the how-to naming convention

* Update actions.md (ISD-2304)

Added link to Juju docs

* Update configurations.md (ISD-2304)

"Configure" --> "Configurations"
Added a link to the Juju docs

* Update backup-and-restore-jenkins.md (ISD-2298)

Changed title to follow how-to naming convention

* Update integrations.md (ISD-2318)

docs/how-to/backup-and-restore-jenkins.md

@@ -1,4 +1,4 @@
-# Backup and restore Jenkins
+# How to back up and restore Jenkins
 A backup is a snapshot of the Jenkins data (jobs, configurations, secrets, plugins, etc.) at a given point in time. This backup can be used to:
 * Restore Jenkins to a previous stable state (during disaster recovery).
 * Migrate data to a new Jenkins charm instance.

docs/index.md

@@ -2,20 +2,37 @@
 
 A Juju charm deploying and managing Jenkins on Kubernetes. [Jenkins](https://www.jenkins.io/) is an open source automation server. Jenkins provides hundreds of plugins to support building, deploying and automating any project. It can be integrated with both k8s and machine (VM) agents for use.
 
-This charm simplifies initial deployment and "day N" operations of Jenkins on Kubernetes, including integration with Jenkins agent instances, automatic patch updates and more. It allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io/) to [Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes offerings.
-
-As such, the charm makes it easy for those looking to take control of their own automation management system whilst keeping operations simple, and gives them the freedom to deploy on the Kubernetes platform of their choice.
+This charm simplifies initial deployment and operations of Jenkins on Kubernetes, including integration with Jenkins agent instances, automatic patch updates and more. It allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io/) to [Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes offerings.
 
 For DevOps or SRE teams this charm will make operating Jenkins simple and straightforward through Juju's clean interface. It will allow easy deployment into multiple environments for testing of changes, and supports scaling out agents for enterprise deployments.
 
+## In this documentation
+
+| | |
+|--|--|
+|  [Tutorials](https://charmhub.io/jenkins-k8s/docs/tutorial-getting-started)</br>  Get started - a hands-on introduction to using the charm for new users </br> |  [How-to guides](https://charmhub.io/jenkins-k8s/docs/how-to-configure-restart-time-range) </br> Step-by-step guides covering key operations and common tasks |
+| [Reference](https://charmhub.io/jenkins-k8s/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/jenkins-k8s/docs/explanation-agent-deprecated-relation) </br> Concepts - discussion and clarification of key topics  |
+
+## Contributing to this documentation
+
+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. 
+Our documentation is hosted on the [Charmhub forum](https://discourse.charmhub.io/) 
+to enable easy collaboration. Please use the "Help us improve this documentation" links on each documentation page to 
+either directly change something you see that's wrong, ask a question or make a suggestion about a potential change via 
+the comments section.
+
+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/jenkins-k8s-operator/issues).
+
 ## Project and community
 
 The Jenkins-k8s 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)
-- [Contribute](Contribute)
+- [Contribute](https://github.com/canonical/jenkins-k8s-operator/blob/94521d904be53c5645881fc43ba0b71ff60b9776/CONTRIBUTING.md)
 
 Thinking about using the Jenkins-k8s Operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!
 
@@ -24,8 +41,16 @@ Thinking about using the Jenkins-k8s Operator for your next project? [Get in tou
 1. [Tutorial](tutorial)
    1. [Getting Started](tutorial/getting-started.md)
 1. [How to](how-to)
+   1. [Backup and restore](how-to/backup-and-restore-jenkins.md)
+   1. [Configure installable plugins](how-to/configure-installable-plugins.md)
+   1. [Configure Jenkins memory usage](how-to/configure-jenkins-memory-usage.md)
    1. [Configure restart-time-range](how-to/configure-restart-time-range.md)
    1. [Get admin password](how-to/get-admin-password.md)
+   1. [Integrate with external agents](how-to/integrate-with-external-agents.md)
+   1. [Integrate with IAM](how-to/integrate-with-iam.md)
+   1. [Integrate with machine agents](how-to/integrate-with-machine-agents.md)
+   1. [Redeploy](how-to/redeploy.md)
+   1. [Resize Jenkins storage](how-to/resize-jenkins-storage.md)
    1. [Rotate credentials](how-to/rotate-credentials.md)
 1. [Reference](reference)
    1. [Actions](reference/actions.md)

docs/reference/actions.md

@@ -1,3 +1,5 @@
 # Actions
 
 See [Actions](https://charmhub.io/jenkins-k8s/actions).
+
+> Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action)

docs/reference/configurations.md

@@ -1,3 +1,5 @@
 # Configurations
 
-See [Configure](https://charmhub.io/jenkins-k8s/configure).
+See [Configurations](https://charmhub.io/jenkins-k8s/configure).
+
+> Read more about configurations in the Juju docs: [Configuration](https://juju.is/docs/juju/configuration)

docs/reference/integrations.md

@@ -2,45 +2,57 @@
 
 ### agent
 
-_Interface_: jenkins_agent_v0
+_Interface_: jenkins_agent_v0    
 _Supported charms_: [jenkins-agent-k8s](https://charmhub.io/jenkins-agent-k8s),
 [jenkins-agent](https://charmhub.io/jenkins-agent)
 
 Jenkins agents provide a way to perform tasks scheduled by the Jenkins server. Jenkins agents are
 used to distribute workload across multiple containers, allowing parallel execution of jobs.
 
-Example agent relate command: `juju relate jenkins-k8s:agent jenkins-agent-k8s:agent`
+Example agent integrate command: 
+```
+juju relate jenkins-k8s:agent jenkins-agent-k8s:agent
+```
 
 To create a [cross model relation](https://juju.is/docs/olm/manage-cross-model-integrations) with
 a jenkins-agent (VM) charm, create an offer from the machine model.
 
-`juju offer jenkins-agent:agent`
+```
+juju offer jenkins-agent:agent
+```
 
 Then, relate the offer from the k8s model where jenkins-k8s charm resides.
 
-`juju relate jenkins-k8s:agent <controller-name>:<juju-user>/<agent-model>.jenkins-agent`
+```
+juju integrate jenkins-k8s:agent <controller-name>:<juju-user>/<agent-model>.jenkins-agent
+```
 
 An example of such command would look like the following, using a jenkins-agent deployed on a
 localhost
 [lxd controller](https://juju.is/docs/olm/get-started-with-juju#heading--prepare-your-cloud).
 
-`juju relate jenkins-k8s:agent localhost:admin/jenkins-vm-model.jenkins-agent`
+```
+juju integrate jenkins-k8s:agent localhost:admin/jenkins-vm-model.jenkins-agent
+```
 
 ### logging
 
-_Interface_: loki_push_api
+_Interface_: loki_push_api    
 _Supported charms_: [loki-k8s](https://charmhub.io/loki-k8s)
 
 Logging relation provides a way to scrape logs produced from the Jenkins server charm. The Jenkins 
 server logs are stored at `/var/lib/jenkins/logs/jenkins.log`. These logs are the same logs as the logs 
 emitted to the standard output. A promtail worker is spawned and will periodically push logs to
 Loki.
 
-Example agent relate command: `juju relate jenkins-k8s:logging loki-k8s:logging`
+Example agent integrate command: 
+```
+juju integrate jenkins-k8s:logging loki-k8s:logging
+```
 
 ### metrics-endpoint
 
-_Interface_: prometheus_scrape
+_Interface_: prometheus_scrape    
 _Supported charms_: [prometheus-k8s](https://charmhub.io/prometheus-k8s)
 
 Metrics-endpoint relation allows scraping the `/prometheus` endpoint provided by Jenkins
@@ -50,12 +62,14 @@ only be scraped by Prometheus once the relation becomes active. For more informa
 metrics exposed, please refer to the
 [`prometheus` plugin documentation](https://plugins.jenkins.io/prometheus/).
 
-Example metrics-endpoint relate command: 
-`juju relate jenkins-k8s:metrics-endpoint prometheus-k8s:metrics-endpoint`
+Example metrics-endpoint integrate command: 
+```
+juju integrate jenkins-k8s:metrics-endpoint prometheus-k8s:metrics-endpoint
+```
 
 ### grafana-dashboard
 
-_Interface_: grafana_dashboard
+_Interface_: grafana_dashboard    
 _Supported charms_: [grafana-k8s](https://charmhub.io/grafana-k8s)
 
 Grafana-dashboard relation enables quick dashboard access already tailored to fit the needs of 
@@ -65,5 +79,11 @@ Performance and Health Overview” under the General section of the dashboard br
 (`/dashboards`). Modifications to the dashboard can be made but will not be persisted upon
 restart/redeployment of the charm.
 
-Grafana-Prometheus relate command: `juju relate grafana-k8s:grafana-source prometheus-k8s:grafana-source`
-Grafana-dashboard relate command: `juju relate jenkins-k8s:grafana-dashboard grafana-k8s:grafana-dashboard`
+Grafana-Prometheus integrate command: 
+```
+juju integrate grafana-k8s:grafana-source prometheus-k8s:grafana-source
+```
+Grafana-dashboard integrate command: 
+```
+juju integrate jenkins-k8s:grafana-dashboard grafana-k8s:grafana-dashboard
+```