Eliminating Vale Warnings

This commit only edits documentation material. The goal was to eliminate a significant chunk of vale warnings. I was able to resolve 150 warnings, which is about 35%.

CONTRIBUTING.md

@@ -1,25 +1,25 @@
 # Contributing to NativeLink
 
 NativeLink welcomes contribution from everyone. Here are the guidelines if you
-are thinking of helping us:
+are thinking of helping:
 
 ## Contributions
 
-Contributions to NativeLink or its dependencies should be made in the form of
-GitHub pull requests. Each pull request will be reviewed by a core contributor
-(someone with permission to land patches) and either landed in the main tree or
-given feedback for changes that would be required. All contributions should
+You can contribute to NativeLink or its dependencies via GitHub pull
+requests. Each pull request will undergo review by a core contributor
+(someone with permission to land patches) and either land in the main tree
+or receive feedback for required changes. All contributions should
 follow this format, even those from core contributors.
 
-Should you wish to work on an issue, please claim it first by commenting on
+To work on an issue, please claim it first by commenting on
 the GitHub issue that you want to work on it. This is to prevent duplicated
 efforts from contributors on the same issue.
 
 ## Git setup
 
 NativeLink has a somewhat specific contribution process to ensure consistent
 quality across all commits. If anything in the following guide is unclear to you
-please raise an issue so that we can clarify this document.
+please raise an issue to help clarify this document.
 
 1. In your [GitHub settings](https://github.com/settings/keys), set up distinct
    authentication and signing keys. For further information see:
@@ -65,8 +65,8 @@ please raise an issue so that we can clarify this document.
 > upstream     [email protected]:TraceMachina/nativelink (push)
 > ```
 
-6. Finally, configure `git` to sign your commits with the keys you set up
-   previously. Create a `.gitconfig` file in your home directory like so:
+6. For the last step, configure `git` to sign your commits with the keys
+   you set up. Create a `.gitconfig` file in your home directory like so:
 
     ```ini
     [user]
@@ -86,15 +86,16 @@ please raise an issue so that we can clarify this document.
 
 ## Local development setup
 
-NativeLink ships almost all of its tooling in a nix flake which is configured
-via a [`flake.nix`](https://github.com/tracemachina/nativelink/tree/main/flake.nix) file in the root of the repository. While it's
+NativeLink ships most of its tooling in a nix flake configured
+via a [`flake.nix`](https://github.com/tracemachina/nativelink/tree/main/flake.nix)
+file in the root of the repository. While it's
 possible to work on some parts of the codebase without this environment, it'll
 make your life much easier since it lets you reproduce most of CI locally.
 
 1. Install Nix with flakes: https://github.com/NixOS/experimental-nix-installer
    For further information on Nix Flakes see: https://nixos.wiki/wiki/Flakes.
 2. Optionally (but highly recommended), install [`direnv`](https://direnv.net/docs/installation.html) and
-   hook it into your shell:
+   integrate it into your shell:
 
    ```bash
    nix profile install nixpkgs#direnv
@@ -166,13 +167,13 @@ NativeLink doesn't allow direct commits or human-created side branches in the
 
    - Use a capital letter to start the commit and use an imperative tone for the
      title.
-   - Don't end the title with a period.
+   - Don't end the title with a punctuation.
    - Keep the first line as short as possible. If your feature is complex, add
-     additional information in the commit message body.
+     extra information in the commit message body.
    - If you feel like you need the word `and` in the commit title, the commit
-     might try to do too many things at once and you should consider splitting
+     might try to do a lot of things at once and you should consider splitting
      it into separate commits.
-   - The commit message body should have a maximum line length of 72 characters.
+   - The length of commit message's body shouldn't exceed 72 characters.
      This is to keep the `git log` readable with raw terminals.
 
    ```bash
@@ -210,7 +211,7 @@ NativeLink doesn't allow direct commits or human-created side branches in the
    remaining issues. Feel free to ask for help if you have trouble getting CI
    for your pull request green.
 
-8. If you need to make additional changes, don't use a regular `git commit` on
+8. If you need to make further changes, don't use a regular `git commit` on
    the pull request branch. Instead use `git commit --amend` and `git push -f`
    to update the commit in-place. The changes between the commit versions will
    remain visible in the Reviewable UI.
@@ -302,14 +303,16 @@ add the changed files manually to the staging area.
 
 ### Setting up rust-analyzer
 
-[rust-analyzer](https://rust-analyzer.github.io/) works reasonably well out of the box due to picking up the manifest for the `nativelink` crate, but it isn't integrated with Bazel by default. In order to generate a project configuration for rust-analyzer,
+[rust-analyzer](https://rust-analyzer.github.io/) works reasonably well out of the box due to picking up the manifest for the `nativelink` crate, but it isn't integrated with Bazel by default. To generate a project configuration for rust-analyzer,
 run the `@rules_rust//tools/rust_analyzer:gen_rust_project` target:
 
 ```sh
 bazel run @rules_rust//tools/rust_analyzer:gen_rust_project
 ```
 
-This will generate a `rust-project.json` file in the root directory. This file needs to be regenerated every time new files or dependencies are added in order to stay up-to-date. You can configure rust-analyzer can pick it up by setting the [`rust-analyzer.linkedProjects`](https://rust-analyzer.github.io/manual.html#rust-analyzer.linkedProjects) [configuration option](https://rust-analyzer.github.io/manual.html#configuration).
+This will generate a `rust-project.json` file in the root directory.
+
+To stay up-to-date, you need to regenerate this file every time new files or dependencies get added. You can configure rust-analyzer to pick it up by setting the [`rust-analyzer.linkedProjects`](https://rust-analyzer.github.io/manual.html#rust-analyzer.linkedProjects) [configuration option](https://rust-analyzer.github.io/manual.html#configuration).
 
 If you use VS Code, you can configure the following `tasks.json` file to automatically generate this file when you open the editor:
 
@@ -388,22 +391,23 @@ bazel test doctests
 
 ## Writing documentation
 
-NativeLink largely follows the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
+NativeLink primarily follows the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
 
 NativeLink implements its documentation style guide via Vale. The pre-commit
-hooks forbid errors but permit warnings and suggestions. To view all of Vale's
-suggestions invoke it directly:
+hooks forbid errors but permit warnings and suggestions. To view every Vale
+suggestion, invoke Vale directly:
 
 ```
 vale somefile
 ```
 
 ## Creating releases
 
-To keep the release process in line with best practices for open source
-repositories, not all steps are automated. Specifically, tags should be signed
-and pushed manually and the release notes should be human readable beyond what
-most automatically generated changelogs provide.
+
+To align the release process with best practices for open source repositories,
+some steps remain un-automated. Specifically, you should sign and push tags manually,
+and ensure the release notes are human-readable, offering more detail than most
+automatically generated changelogs.
 
 1. Bump the current version in the following files:
 
@@ -418,7 +422,7 @@ most automatically generated changelogs provide.
 
 3. Create the commit and PR. Call it `Release NativeLink v0.x.y`.
 
-4. Once the PR is merged, update your local repository and origin:
+4. After merging the PR, update your local repository and origin:
 
    ```bash
    git switch main
@@ -442,15 +446,16 @@ most automatically generated changelogs provide.
    git push origin v0.x.y
    ```
 
-7. Pushing the tag triggers an additional GHA workflow which should create the
+7. Pushing the tag triggers an extra GHA workflow which should create the
    container images in your own fork. Check that this workflow is functional. If
    the CI job in your fork passes, push the tag to upstream:
 
    ```bash
    git push upstream v0.x.y
    ```
 
-8. The images for the release are now being created. Go to the [Tags](https://github.com/TraceMachina/nativelink/tags)
+8. The images for the release are now getting created. Go to the
+   [Tags](https://github.com/TraceMachina/nativelink/tags)
    tab in GitHub and double-check that the tag has a green `Verified` marker
    next to it. If it does, select `Create a release from tag` and create release
    notes. You can use previous release notes as template by clicking on the
@@ -460,7 +465,7 @@ most automatically generated changelogs provide.
    Make sure to include migration instructions for all breaking changes.
 
    Explicitly list whatever changes you think are worth mentioning as `Major
-   changes`. This is a fairly free-form section that doesn't have any explicit
+   changes`. This is a free-form section that doesn't have any explicit
    requirements other than being a best-effort summary of notable changes.
 
 9. Once all notes are in line, click `Publish Release`.

README.md

@@ -16,11 +16,11 @@
 [![Slack](https://img.shields.io/badge/slack--channel-blue?logo=slack)](https://nativelink.slack.com/join/shared_invite/zt-281qk1ho0-krT7HfTUIYfQMdwflRuq7A#/shared-invite/email)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## What's NativeLink?
+## What's NativeLink
 
-NativeLink is an efficient, high-performance build cache and remote execution system that accelerates software compilation and testing while reducing infrastructure costs. It optimizes build processes for projects of all sizes by intelligently caching build artifacts and distributing tasks across multiple machines.
+NativeLink is an efficient, high-performance build cache and remote operation system that accelerates software compilation and testing while reducing infrastructure costs. It optimizes build processes for projects of all sizes by intelligently caching build artifacts and distributing tasks across several machines.
 
-NativeLink is trusted in production environments to reduce costs and developer iteration times--handling over **one billion requests** per month for its customers, including large corporations such as **Samsung**.
+Users trust NativeLink in production environments to reduce costs and developer iteration times--handling over **one billion requests** per month for its customers, including large corporations such as **Samsung**.
 
 <a href="https://www.youtube.com/watch?v=WLpqFuyLMUQ">
     <img src="https://trace-github-resources.s3.us-east-2.amazonaws.com/harper-90-thumbnail.webp" alt="NativeLink Explained in 90 seconds" loading="lazy" width="480" height="360" />
@@ -30,9 +30,9 @@ NativeLink is trusted in production environments to reduce costs and developer i
 
 1. **Advanced Build Cache**:
    - Stores and reuses results of previous build steps for unchanged components
-   - Significantly reduces build times, especially for incremental changes
+   - Dramatically reduces build times, notably for incremental changes
 
-2. **Efficient Remote Execution**:
+2. **Efficient Remote Operation**:
    - Distributes build and test tasks across a network of machines
    - Parallelizes workloads for faster completion
    - Utilizes remote resources to offload computational burden from local machines
@@ -42,14 +42,14 @@ NativeLink seamlessly integrates with build tools that use the Remote Execution
 
 ## 🚀 Quickstart
 
-To start, you can deploy NativeLink as a Docker image (as shown below) or by using our cloud-hosted solution, [NativeLink Cloud](https://app.nativelink.com). It's **FREE** for individuals, open-source projects, and cloud production environments, with support for unlimited team members.
+To start, you can deploy NativeLink as a Docker image (as shown below) or by using a cloud-hosted solution provided by the NativeLink team - [NativeLink Cloud](https://app.nativelink.com). It's **FREE** for individuals, open-source projects, and cloud production environments, with support for unlimited team members.
 
 The setups below are **production-grade** installations. See the [contribution docs](https://docs.nativelink.com/contribute/nix/) for instructions on how to build from source with [Bazel](https://docs.nativelink.com/contribute/bazel/), [Cargo](https://docs.nativelink.com/contribute/cargo/), and [Nix](https://docs.nativelink.com/contribute/nix/).
 
 
 ### 📦 Prebuilt images
 
-Fast to spin up, but currently limited to `x86_64` systems. See the [container
+Fast to spin up, but limited to `x86_64` systems at the moment. See the [container
 registry](https://github.com/TraceMachina/nativelink/pkgs/container/nativelink)
 for all image tags and the [contribution docs](https://docs.nativelink.com/contribute/nix)
 for how to build the images yourself.
@@ -117,14 +117,14 @@ See the [contribution docs](https://docs.nativelink.com/contribute/nix) for furt
 
 ## 🤝 Contributing
 
-Visit our [Contributing](https://github.com/tracemachina/nativelink/blob/main/CONTRIBUTING.md) guide to learn how to contribute to NativeLink. We welcome contributions from developers of all skill levels and backgrounds!
+Visit the [Contributing](https://github.com/tracemachina/nativelink/blob/main/CONTRIBUTING.md) guide to learn how to contribute to NativeLink. Contributions from developers of all skill levels and backgrounds are welcome!
 
 ## 📊 Stats
 
 ![Alt](https://repobeats.axiom.co/api/embed/d8bfc6d283632c060beaab1e69494c2f7774a548.svg "Repobeats analytics image")
 
 ## 📜 License
 
-Copyright 2020–2024 Trace Machina, Inc.
+Copyright 2020 through 2024 Trace Machina, Inc.
 
 Licensed under the Apache 2.0 License, SPDX identifier `Apache-2.0`.

SECURITY.md

@@ -9,8 +9,7 @@ vulnerabilities. Please send a report if something doesn't look right.
 ## Supported versions
 
 At the moment no version of `nativelink` is officially supported. Consider
-using the latest commit on the `main` branch until official production binaries
-are released.
+using the latest commit on the `main` branch until the release of official production binaries.
 
 ## Reporting a vulnerability
 
@@ -31,9 +30,9 @@ for publicly disclosed vulnerabilities.
 See the published [OCI images](https://github.com/TraceMachina/nativelink/pkgs/container/nativelink)
 for pull commands.
 
-Images are tagged by nix derivation hash. The most recently pushed image
-corresponds to the `main` branch. Images are signed by the GitHub action that
-produced the image. Note that the [OCI workflow](https://github.com/TraceMachina/nativelink/actions/workflows/image.yaml) might take a few minutes to publish the latest image.
+Nix derivation hash tag the images. The latest pushed image
+corresponds to the `main` branch. GitHub action producing an image signs that
+image. Note that the [OCI workflow](https://github.com/TraceMachina/nativelink/actions/workflows/image.yaml) might take some time to publish the latest image.
 
 ### Get the tag for the latest commit
 ```sh
@@ -58,6 +57,6 @@ export PINNED_TAG=$(nix eval github:TraceMachina/nativelink/<revision>#image.ima
 > [!TIP]
 > The images are reproducible on `X86_64-unknown-linux-gnu`. If you're on such a
 > system you can produce a binary-identical image by building the `.#image`
-> flake output locally. Make sure that your `git status` is completely clean and
+> flake output locally. Make sure that your `git status` is clean and
 > aligned with the commit you want to reproduce. Otherwise the image will be
 > tainted with a `"dirty"` revision label.

deployment-examples/chromium/README.md

@@ -6,18 +6,18 @@ and worker. Don't use this example deployment in production. It's insecure.
 > [!WARNING]
 > - The client build request is best done from a Ubuntu image, `./03_build_chrome_tests.sh`. It will check if the image is Ubuntu and
 > fail otherwise.
-> - This tutorial has been tested in a Nix environment of version `2.
+> - This tutorial underwent testing in a Nix environment of version `2.
 > 21.0`.
 > - You need to install the [Docker](https://docs.docker.com/engine/install/ubuntu/) Engine in Ubuntu.
 > - To get your Nix environment set up see the [official Nix installation documentation](https://nix.dev/install-nix).
 
-All commands should be run from nix to ensure all dependencies exist in the environment.
+Run all commands from nix to ensure all dependencies exist in the environment.
 
 ```bash
 nix develop
 ```
 
-In this example we're using `kind` to set up the cluster `cilium` to provide a
+This example uses `kind` to set up the cluster `cilium` to provide a
 `LoadBalancer` and `GatewayController`.
 
 First set up a local development cluster:
@@ -30,8 +30,7 @@ native up
 > The `native up` command uses Pulumi under the hood. You can view and delete
 > the stack with `pulumi stack` and `pulumi destroy`.
 
-Next start a few standard deployments. This part also builds the remote
-execution containers and makes them available to the cluster:
+Next, start some standard deployments. This step includes building and preparing the remote containers for use in the cluster.:
 
 ```bash
 ./01_operations.sh
@@ -42,7 +41,7 @@ execution containers and makes them available to the cluster:
 > `nativelink` and worker images. You can view the state of the pipelines with
 > `tkn pr ls` and `tkn pr logs`/`tkn pr logs --follow`.
 
-Finally, deploy NativeLink:
+Time to deploy NativeLink:
 
 ```bash
 ./02_application.sh
@@ -74,7 +73,7 @@ in [linux/build_instructions.md](https://chromium.googlesource.com/chromium/src/
 ```
 
 > [!TIP]
-> You can monitor the logs of container groups with `kubectl logs`:
+> Use `kubectl logs` to view container group logs:
 > ```bash
 > kubectl logs -f -l app=nativelink-cas
 > kubectl logs -f -l app=nativelink-scheduler