docs: enable vale style checks (#571)

* update docs according to vale style check warnings

* update docs according to vale style check warnings

* enable vale-style-check

* Apply suggestions from code review

Co-authored-by: Erin Conley <[email protected]>

---------

Co-authored-by: Erin Conley <[email protected]>

Author: cbartz

.github/workflows/test.yaml

@@ -10,3 +10,4 @@ jobs:
     with:
       self-hosted-runner: true
       self-hosted-runner-label: edge
+      vale-style-check: true

docs/changelog.md

@@ -1,9 +1,13 @@
 # Changelog
 
+This changelog documents user-relevant changes to the GitHub runner charm.
+
+
 ### 2025-06-17
 
 - Fix bug where SSH connection error always appears in the logs.
 
+
 ### 2025-06-16
 
 - Revert copytruncate logrotate method for reactive processes, as copytruncate keeps log files on disks and does not remove them, and each process is writing to a new file leading to a huge and increasing amount

docs/how-to/openstack-runner.md

@@ -29,7 +29,7 @@ The first cloud in the `clouds.yaml` is used by the charm.
 
 Here is a sample of the `clouds.yaml`:
 
-```yaml
+```
 clouds:
   cloud:
     auth:

docs/index.md

@@ -8,7 +8,7 @@ For the github-runner-operator charm, this includes:
 * Configurable resource limits.
 * Ability to redeploy without losing any data (no need to back up).
 * Supported observability through the `cos-agent` integration.
-* Scheduled dependences upgrades to mitigate security risks. Furthermore, the landscape-client charm can be deployed with this charm to ensure other dependencies are kept up to date.
+* Scheduled dependences upgrades to mitigate security risks. Furthermore, the Landscape Client charm can be deployed with this charm to ensure other dependencies are kept up to date.
 
 Operating a self-hosted runner comes with [certain security concerns according to GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security).
 Just like GitHub's runners, the self-hosted runners managed by the charm are isolated in a single-use virtual machine.
@@ -24,7 +24,10 @@ The charm enforces a set of GitHub repository settings as best practice. This is
 |  [Overview](https://charmhub.io/github-runner)</br>  Overview of the charm </br> | [How-to guides](https://charmhub.io/github-runner/docs/how-to-openstack-runner) </br> Step-by-step guides covering key operations and common tasks |
 | [Reference](https://charmhub.io/github-runner/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture) </br> Concepts - discussion and clarification of key topics  |
 
+<!-- vale Canonical.004-Canonical-product-names = NO -->
 If you want to use ephemeral LXD virtual machines spawned by charm, you can refer to the section [Track local-lxd](https://charmhub.io/github-runner/docs/local-lxd).
+<!-- vale Canonical.004-Canonical-product-names = YES -->
+
 
 ## Contributing to this documentation
 
@@ -44,7 +47,7 @@ The GitHub runner charm is a member of the Ubuntu family. It's an open-source pr
 Thinking about using the GitHub runner charm for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!
 
 # Contents
-
+<!-- vale Canonical.004-Canonical-product-names = NO -->
 1. [How to](how-to)
   1. [Change repository or organization](how-to/change-path.md)
   1. [Change GitHub personal access token](how-to/change-token.md)
@@ -95,4 +98,5 @@ Thinking about using the GitHub runner charm for your next project? [Get in touc
   1. [Explanation](local-lxd/explanation)
     1. [ARM64](local-lxd/explanation/arm64.md)
     1. [Charm architecture](local-lxd/explanation/charm-architecture.md)
-    1. [SSH Debug](local-lxd/explanation/ssh-debug.md)
+    1. [SSH Debug](local-lxd/explanation/ssh-debug.md)
+<!-- vale Canonical.004-Canonical-product-names = YES -->

docs/local-lxd/explanation/arm64.md

@@ -1,6 +1,7 @@
 # ARM64
 
-### Nested virtualiztion support
+
+For ARM64, the charm needs to be deployed on a bare metal instance. This is due to the fact that the
 
 GitHub runner uses [LXD](https://github.com/canonical/lxd) to create a virtual machine to run the 
 GitHub runner's binary. Some versions of the ARM64 architecture do not support nested 
@@ -22,4 +23,6 @@ to be further developed.
 - Kernel (KVM): upstream not yet ready
 - Userspace programs (e.g. qemu): unsupported.
 
-Therefore, it is currently necessary that the charm is deployed on a bare metal instance.
+Therefore, it is currently necessary that the charm is deployed on a bare metal instance.
+For instance, you can use any of the [ARM64 metal instances](https://aws.amazon.com/ec2/instance-types/) to provide Juju
+with ARM64 bare metal instances. Some of the examples include: a1.metal, m7g.metal.

docs/local-lxd/explanation/charm-architecture.md

@@ -41,11 +41,13 @@ The software installed in the image includes:
   - `yq`
 
 The configurations applied in the image include:
-
+<!-- vale Canonical.005-Industry-product-names = NO -->
 - Creating a group named `microk8s`.
 - Adding the `ubuntu` user to the `microk8s` group. Note that the `microk8s` package is not installed in the image; this preconfigures the group for users who install the package.
 - Adding the `ubuntu` user to the `docker` group.
 - Adding iptables rules to accept traffic for the DOCKER-USER chain. This resolves a networking conflict with LXD.
+<!-- vale Canonical.005-Industry-product-names = YES -->
+
 
 ## Network configuration
 

docs/local-lxd/reference/arm64.md

@@ -1,5 +1,7 @@
 # Integrations
 
+This is a list of relations supported by the GitHub Runner charm.
+
 ## debug-ssh
 
 _Interface_: debug-ssh    

docs/local-lxd/reference/integrations.md

@@ -1,5 +1,8 @@
 # Token scopes
 
+In order to use the GitHub runner charm, a personal access token with the necessary permissions
+is required.
+
 ## Fine grained access token scopes
 
 **Note**: In addition to having a token with the necessary permissions, the user who owns the
@@ -34,6 +37,9 @@ repository runner.
 
 ## Personal access token scopes
 
+Depending on whether the charm is used for GitHub organizations or repositories, the following scopes
+should be selected when creating a personal access token.
+
 ### Organizational Runners
 
 To use this charm for GitHub organizations, the following scopes should be selected:

docs/local-lxd/reference/token-scopes.md

@@ -1,5 +1,8 @@
 # Deploy the GitHub runner charm for the first time
 
+This tutorial shows you how to deploy the GitHub runner charm for the first time using Juju on a local LXD controller.
+The charm will deploy a self-hosted runner that can be used to run GitHub Actions jobs.
+
 ## What you'll do
 
 - Set up a GitHub repository
@@ -80,7 +83,7 @@ Replacing the `<TOKEN>` with the personal access token, and `<OWNER/REPO>` the G
 
 The `--constraints` option for the `juju deploy` sets the resource requirements for the Juju machine hosting the charm application. This is used to accommodate different sizes of self-hosted runners. For details, refer to [Managing resource usage](https://charmhub.io/github-runner/docs/managing-resource-usage).
 
-The `--storage` option mounts a juju storage to be used as the disk for LXD instances hosting the self-hosted runners. Refer [How to configure runner storage](https://charmhub.io/github-runner/docs/configure-runner-storage) for more information.
+The `--storage` option mounts a Juju storage to be used as the disk for LXD instances hosting the self-hosted runners. Refer [How to configure runner storage](https://charmhub.io/github-runner/docs/configure-runner-storage) for more information.
 
 The charm performs various installation and configuration on startup. The charm might upgrade the kernel of the Juju machine and reboot the Juju machine. During reboot, the Juju machine will go into the `down` state; this is a part of the normal reboot process and the Juju machine should be restarted after a while.