Update docs (#189)

* Update outdated links

* Update getting-started.md

- Capitalise Juju and MicroK8s where appropriate
- Update outdated commands
- Remove broken links in the "What you'll do" section
- Remove words for conciseness

* Update configure-restart-time-range.md

Add a "the"

* Update backup-and-restore-jenkins.md

- Capitalise Pebble where appropriate
- Update list items to contain the same grammatical structure.

* Update configure-installable-plugins.md

- Moved the code block higher in the section (I think it makes more sense for the `update-status` text to appear after the code block; please let me know if you disagree!)
- Fixed a fragmented sentence
- Other grammatical changes

* Update configure-jenkins-memory-usage.md

- Capitalise Juju where appropriate
- Change the "considerations" header to be one level lower than the "how to" header

* Update outdated command in get-admin-password.md

I removed the `--wait` flag because it now requires an argument. I'm not opposed to adding it back, but I would need guidance on an appropriate value to include.

* Change a header in integrate-with-external-agents.md

Made "Networking considerations" heading one level lower than the "how to" heading.

* Update redeploy.md

Removed the second section and moved text around for conciseness. Also updated the steps to have the same grammatical structure.

* fixed broken link

* Update resize-jenkins-storage.md

Fix broken links; small grammatical changes

* Update rotate-credentials.md

Updated an outdated command (removed the `--wait` flag, but not opposed to putting it back in); explicitly labeled the password as new

* Update external-access.md

Fixed a fragmented sentence; grammatical change in last sentence

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

@@ -8,7 +8,7 @@ A backup is a snapshot of the Jenkins data (jobs, configurations, secrets, plugi
 From [Backing-up/Restoring Jenkins](https://www.jenkins.io/doc/book/system-administration/backing-up/), This script backs up the most essential files as mentioned in the article:
 * The `master.key` file.
 * Job-related files in the `./jobs`, `./builds` and `./workspace` folders.
-* Plugins (`.hpi` and `.jpi` files) in the `./plugins` folder
+* Plugin-related files (`.hpi` and `.jpi`) in the `./plugins` folder.
 
 ```bash
 cat <<EOF > backup.sh
@@ -55,7 +55,7 @@ juju ssh --container jenkins $JENKINS_UNIT chown -R jenkins:jenkins /backup
 juju ssh --container jenkins $JENKINS_UNIT cp -avR /backup/* /var/lib/jenkins
 juju ssh --container jenkins $JENKINS_UNIT rm -rf /backup /jenkins_backup.tar.gz
 ```
-2. Restart pebble for the changes to take effect
+2. Restart Pebble for the changes to take effect.
 ```bash
 juju ssh --container jenkins $JENKINS_UNIT pebble restart jenkins
 ```

docs/how-to/configure-installable-plugins.md

@@ -2,21 +2,22 @@
 
 ### Configure `plugins`
 
-Use the `plugins` configuration to allow a list of plugins to be installed on Jenkins.
-Comma-separated list of allowed plugin short names. If empty, any plugin can be installed.
-Plugins installed by the user and their dependencies will be removed automatically if not on
+Use the `plugins` configuration to allow plugins to be installed on Jenkins.
+The configuration is a comma-separated list of allowed plugin short names. If empty, any plugin can be installed.
+Plugins installed by the user and the plugins' dependencies will be removed automatically if they are not on
 the list. Included plugins are not automatically installed.
-The plugins are cleaned up at `update-status` hook trigger. If the `restart-time-range`
-configuration option is provided, the plugins are cleaned up during the defined time range.
-
-On trigger it will:
-
-1. Delete any installed plugins not defined on the list and their dependencies.
-2. Set a system message on Jenkins indicating which user installed plugins have been deleted.
 
 ```
 juju config jenkins-k8s plugins=<allowed-plugins-csv>
 
 # plugins example: `git, azure-cli, aws-credentials` will allow git, azure and aws-credentials
 plugins to be installed.
 ```
+
+The plugins are cleaned up at `update-status` hook trigger. If the `restart-time-range`
+configuration option is provided, the plugins are cleaned up during the defined time range.
+
+On trigger it will:
+
+1. Delete any installed plugins not defined on the list and their dependencies.
+2. Set a system message on Jenkins indicating which user installed plugins have been deleted.

docs/how-to/configure-jenkins-memory-usage.md

@@ -1,5 +1,5 @@
 # How to control heap memory of the jenkins-k8s-operator charm
-The [jenkins-k8s-operator](https://github.com/canonical/jenkins-k8s-operator) charm uses [juju constraints](https://juju.is/docs/juju/constraint) to limit the amount of memory a charm can use. To deploy the charm with constraints, use the `--constraints "<key>=<value>"` option when running `juju deploy`:
+The [jenkins-k8s-operator](https://github.com/canonical/jenkins-k8s-operator) charm uses [Juju constraints](https://juju.is/docs/juju/constraint) to limit the amount of memory a charm can use. To deploy the charm with constraints, use the `--constraints "<key>=<value>"` option when running `juju deploy`:
 ```bash
 juju deploy jenkins-k8s --channel=latest/edge --constraints "mem=2048M"
 ```
@@ -9,5 +9,5 @@ juju set-constraints jenkins-k8s "mem=4096M"
 ```
 Other types of constraints (like cores, disk, etc.) can also be applied. Note that this value affects the shared maximum memory between the `charm` container and `jenkins` container.
 
-# Considerations when applying memory constraints
-Constraints set this way directly influence the amount of heap memory available to the JVM, with a ratio `JVM heap / Container Memory limit` of 0.5. For example, a `jenkins-k8s-operator` charm deployed with `--constraints "mem=1024M"` would set a maximum heap memory size of 512Mb. Too little heap memory can result in the controller getting restarted due to Out-of-memory(OOM) error. Make sure to adapt the memory constraints based on your workload.
+## Considerations when applying memory constraints
+Constraints set this way directly influence the amount of heap memory available to the JVM, with a ratio `JVM heap / Container Memory limit` of 0.5. For example, a `jenkins-k8s-operator` charm deployed with `--constraints "mem=1024M"` would set a maximum heap memory size of 512Mb. Too little heap memory can result in the controller getting restarted due to Out-of-memory (OOM) error. Make sure to adapt the memory constraints based on your workload.

docs/how-to/configure-restart-time-range.md

@@ -9,7 +9,7 @@ Use the `restart-time-range` configuration to set the time interval when `jenkin
 2. automatically remove plugins that are installed on the system but are not part of the `plugins`
    configuration option.
 
-The minimum time interval is 1 hour. Time range is applied each day of the week.
+The minimum time interval is 1 hour. The time range is applied each day of the week.
 
 ```
 juju config jenkins-k8s restart-time-range=<desired-time-range>

docs/how-to/get-admin-password.md

@@ -5,7 +5,7 @@
 To retrieve the password for the admin account, you can run the `get-admin-password` action.
 
 ```
-juju run-action jenkins-k8s/0 get-admin-password --wait
+juju run jenkins-k8s/0 get-admin-password 
 ```
 
 The output should look something similar to the contents below:

docs/how-to/integrate-with-external-agents.md

@@ -13,8 +13,8 @@ juju integrate jenkins-k8s:agent-discovery-ingress traefik-k8s:ingress
 juju integrate jenkins-k8s:agent <offer-endpoint>
 ```
 
-# Networking considerations
+## Networking considerations
 The charm assumes that:
 1. There are connectivity between the juju controller of the `jenkins-k8s` charm and the juju controller of the agent charm trying to connect with the `jenkins-k8s` charm.
 2. The agent can resolve the ingress hostname provided by the `jenkins-k8s` charm and the resulting IP address is reachable, and there are firewall rules in place to allow HTTP traffic.
-3. In case a reverse proxy is present, it is also expected that the HTTP connection coming from the agent charm is allowed to be upgraded into a Websocket connection. The reverse proxy should also be configured with a suitable idle timeout for websocket connections to avoid intermittent agent disconnection.
+3. In case a reverse proxy is present, it is also expected that the HTTP connection coming from the agent charm is allowed to be upgraded into a Websocket connection. The reverse proxy should also be configured with a suitable idle timeout for websocket connections to avoid intermittent agent disconnection.

docs/how-to/redeploy.md

@@ -2,16 +2,12 @@
 
 Redeployment is a process where the old charm instance is removed and data is migrated to a new charm instance. Redeploying the Jenkins charm consists of 3 steps:
 
-1. Create the new Jenkins charm instance
+1. Create the new Jenkins charm instance:
 ```bash
 juju deploy jenkins-k8s jenkins-k8s-new
 ```
-2. Migrate Jenkins data
-See the `Migrate Jenkins data` section below.
-3. Remove the old Jenkins charm instance
+2. Migrate Jenkins data: Follow the instructions in [the charm's documentation for backup and restore](https://charmhub.io/jenkins-k8s/docs/how-to-backup-and-restore-jenkins).
+3. Remove the old Jenkins charm instance:
 ```bash
 juju remove-application jenkins-k8s
 ```
-
-### Migrate Jenkins data
-Follow the instructions in [the charm's documentation for backup and restore](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to migrate the data to the new Jenkins charm instance.

docs/how-to/resize-jenkins-storage.md

@@ -4,14 +4,14 @@ The default size of the jenkins-home storage volume for a fresh installation is
 A low disk-space on the built-in node will cause the node to go offline, blocking Jenkins from running jobs.
 
 ### Create a backup of the current Jenkins charm instance
-Follow the `Create a backup` section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system
+Follow the "Create a backup" section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/how-to-backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system
 
 ### Deploy the new Jenkins charm instance, specifying the size of the storage volume
-Create a new application with the `--storage` flag. In this example we'll deploy the charm with a storage of 10GB
+Create a new application with the `--storage` flag. In this example we'll deploy the charm with a storage of 10GB:
 ```bash
 juju deploy jenkins-k8s-new --storage jenkins-home=10GB
 ```
 
 ### Restore the created backup onto the newly created Jenkins charm instance
-Follow the `Restore the backup on a new (or existing) charm instance` section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system. Remember to update the `JENKINS_UNIT` environment variable. For our example we have `JENKINS_UNIT=jenkins-k8s-new/0`
+Follow the "Restore the backup on a new (or existing) charm instance" section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/how-to-backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system. Remember to update the `JENKINS_UNIT` environment variable. For our example we have `JENKINS_UNIT=jenkins-k8s-new/0`.
 

docs/how-to/rotate-credentials.md

@@ -6,7 +6,7 @@ To rotate credentials for the admin account and invalidate all logged in user se
 `rotate-credentials` action.
 
 ```
-juju run-action jenkins-k8s/0 rotate-credentials --wait
+juju run jenkins-k8s/0 rotate-credentials 
 ```
 
 The output should look similar to the contents below:
@@ -16,7 +16,7 @@ unit-jenkins-k8s-0:
   UnitId: jenkins-k8s/0
   id: "1"
   results:
-    password: <password>
+    password: <new password>
   status: completed
   timing:
     completed: <timestamp>

docs/index.md

@@ -14,10 +14,10 @@ The Jenkins-k8s Operator is a member of the Ubuntu family. It's an open source p
 
 - [Code of conduct](https://ubuntu.com/community/code-of-conduct)
 - [Get support](https://discourse.charmhub.io/)
-- [Join our online chat](https://chat.charmhub.io/charmhub/channels/charm-dev)
+- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
 - [Contribute](Contribute)
 
-Thinking about using the Jenkins-k8s Operator for your next project? [Get in touch](https://chat.charmhub.io/charmhub/channels/charm-dev)!
+Thinking about using the Jenkins-k8s Operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!
 
 # Contents
 

docs/reference/external-access.md

@@ -16,4 +16,4 @@ The Jenkins charm requires access to the following domains to install Jenkins an
 
 Depending on the localisation, some region-specific external mirrors might also be used. You can find more information on the [list of mirrors for Jenkins](https://get.jenkins.io/war/2.456/jenkins.war?mirrorstats).
 
-Some plugins can also require external access, such as `github.com` for the [Github branch source plugin](https://plugins.jenkins.io/github-branch-source/). Or an external Kubernetes cluster if you are using the [Kubernetes plugin](https://plugins.jenkins.io/kubernetes/). Refer to the documentation of the plugin for more details.
+Some plugins can also require external access, such as `github.com` for the [Github branch source plugin](https://plugins.jenkins.io/github-branch-source/) or an external Kubernetes cluster if you are using the [Kubernetes plugin](https://plugins.jenkins.io/kubernetes/). Refer to the plugin's documentation for more details.

docs/tutorial/getting-started.md

@@ -3,23 +3,23 @@
 ## What you'll do
 
 - Deploy the [jenkins-k8s charm](https://charmhub.io/jenkins-k8s)
-- [Deploy and integrate agents](#deploy-and-relate-agents)
-- [Get admin password](#get-admin-password)
+- Deploy and integrate agents
+- Get admin password
 
 The jenkins-k8s charm helps deploy a Jenkins automation server application with ease and
 also helps operate the charm. This
 tutorial will walk you through each step of deployment to get a basic Jenkins server deployment.
 
 ### Prerequisites
 
-To deploy jenkins-k8s charm, you will need a juju bootstrapped with any kubernetes controller.
-To see how to bootstrap your juju installation with microk8s, please refer to the documentation
-on microk8s [installation](https://juju.is/docs/olm/microk8s).
+To deploy jenkins-k8s charm, you will need a Juju bootstrapped with any Kubernetes controller.
+To see how to bootstrap your Juju installation with MicroK8s, please refer to the documentation
+on MicroK8s [installation](https://juju.is/docs/olm/microk8s).
 
-### Setting up the tutorial model
+### Set up the tutorial model
 
 To easily clean up the resources and to separate your workload from the contents of this tutorial,
-it is recommended to set up a new model with the following command.
+set up a new Juju model with the following command.
 
 ```
 juju add-model jenkins-tutorial
@@ -64,7 +64,7 @@ By running the `get-admin-password` action on a jenkins-k8s unit, juju will read
 admin credentials setup for you. You can use the following command below.
 
 ```
-juju run-action jenkins-k8s/0 get-admin-password --wait
+juju run jenkins-k8s/0 get-admin-password 
 ```
 
 The output should look something similar to the contents below:
@@ -91,5 +91,5 @@ Congratulations! You have successfully finished the jennkins-k8s tutorial. You c
 model environment that you’ve created using the following command.
 
 ```
-juju destroy model jenkins-tutorial -y --release-storage
+juju destroy-model jenkins-tutorial --destroy-storage
 ```