From b08fa0cf8b9be2461b96b29352214be82f638199 Mon Sep 17 00:00:00 2001
From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>
Date: Mon, 29 May 2023 10:20:40 +0200
Subject: [PATCH] docs: drop weasel words (#22165)

Co-authored-by: Rhys Arkins <rhys@arkins.net>
---
 .github/label-actions.yml                     |  2 +-
 docs/development/best-practices.md            | 11 ++++---
 docs/development/design-decisions.md          |  2 +-
 docs/development/help-us-help-you.md          |  6 ++--
 docs/development/local-development.md         |  8 ++---
 docs/development/minimal-reproductions.md     |  5 +--
 docs/development/triage-guide.md              |  6 ++--
 docs/usage/configuration-options.md           | 31 ++++++++++---------
 docs/usage/configuration-templates.md         |  4 +--
 docs/usage/dependency-pinning.md              |  6 ++--
 docs/usage/docker.md                          | 12 +++----
 docs/usage/examples/self-hosting.md           |  4 +--
 docs/usage/faq.md                             |  2 +-
 .../getting-started/installing-onboarding.md  |  2 +-
 .../usage/getting-started/private-packages.md |  4 +--
 docs/usage/key-concepts/automerge.md          |  2 +-
 docs/usage/key-concepts/presets.md            |  3 +-
 docs/usage/key-concepts/pull-requests.md      |  8 ++---
 docs/usage/known-limitations.md               |  2 +-
 docs/usage/noise-reduction.md                 |  2 +-
 docs/usage/self-hosted-configuration.md       |  8 +++--
 lib/modules/manager/argocd/readme.md          |  5 +--
 lib/modules/manager/kubernetes/readme.md      |  5 +--
 lib/modules/manager/regex/readme.md           |  2 --
 lib/modules/versioning/loose/readme.md        |  4 ++-
 25 files changed, 79 insertions(+), 67 deletions(-)

diff --git a/.github/label-actions.yml b/.github/label-actions.yml
index 5e85dbe272..c1d6212df7 100644
--- a/.github/label-actions.yml
+++ b/.github/label-actions.yml
@@ -168,7 +168,7 @@
     Hi there,
 
 
-    You are using simple `done` comments which cause a lot of noise.
+    You are using `done` comments which cause a lot of noise.
     Instead, please use GitHub's web interface to request another review.
     Please read our [contributing guidelines](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md#resolve-review-comments-instead-of-commenting) to reduce noise.
 
diff --git a/docs/development/best-practices.md b/docs/development/best-practices.md
index 30cec02983..2a78558b07 100644
--- a/docs/development/best-practices.md
+++ b/docs/development/best-practices.md
@@ -68,12 +68,15 @@ Function expressions may only be used if dynamically rebinding `this` is needed.
 
 Source: [Google TypeScript Style Guide, function declarations](https://google.github.io/styleguide/tsguide.html#function-declarations).
 
-## Code simplicity
+## Code style
 
-### Write simple code
+### Write understandable code
 
-Simple code is easy to read, review and maintain.
-Choose to write verbose and understandable code instead of "clever" code which might take someone a few attempts to understand what it does.
+Write code that is easier to read, review and maintain.
+Avoid "clever" code that's hard to understand.
+
+Prefer verbose code which is easier for others to read and maintain than concise code which may be hard or slower for others to understand.
+For example, Array `reduce()` functions are often hard to understand first time, and can be replaced with simpler `for` loops which run just as fast but are simpler to understand and maintain.
 
 #### Write single purpose functions
 
diff --git a/docs/development/design-decisions.md b/docs/development/design-decisions.md
index e45afb458e..1e420b232e 100644
--- a/docs/development/design-decisions.md
+++ b/docs/development/design-decisions.md
@@ -86,7 +86,7 @@ This allows users to close unwelcome upgrade PRs and not worry about them being
 ## Rebasing Unmergeable Pull Requests
 
 With the default behavior of one branch per dependency, it's often the case that a PR gets merge conflicts after an adjacent dependency update is merged.
-Although platforms often have a web interface for simple merge conflicts, this is still annoying to resolve manually.
+On most platforms you can use a web interface to resolve merge conflicts, but you're still resolving the conflicts manually, which is annoying.
 
 `renovate` will rebase any unmergeable branches and add the latest necessary commit on top of the most recent `main` commit.
 
diff --git a/docs/development/help-us-help-you.md b/docs/development/help-us-help-you.md
index 9328db964c..3dd587557a 100644
--- a/docs/development/help-us-help-you.md
+++ b/docs/development/help-us-help-you.md
@@ -48,7 +48,7 @@ If you feel frustrated because better documentation would have prevented you fro
 Sometimes people appear to feel frustrated that their issue or discussion has not got enough attention, and they start commenting on other issues with text such as "I'm also having problems with Gradle! See issue #xyz".
 Such comments appear intended to "pressure" Renovate maintainers into taking notice, and rarely do they benefit the people subscribed to the other, mostly-unrelated issues.
 Please do not do it.
-Select the "Subscribe" button on other issues if you just want to follow them.
+Instead, use the "Subscribe" button to follow issues.
 
 ## Reproduce repositories on github.com
 
@@ -68,7 +68,7 @@ Unless you're planning to work on the feature or fix yourself, please be respect
 If you've been asked to give us the logs in an issue or discussion, please don't copy/paste the entire output and expect someone else to sort through thousands of lines to help you.
 A full log dump takes a lot of time to scroll through, and it is next to impossible to do so from mobile.
 
-Instead, please select the logs relevant to your problem and paste just those.
+Instead, please select the logs relevant to your problem and paste only the relevant logs.
 If it turns out there's a need for the full dump, someone can ask you for it later.
 
 ## Avoid unjustified bug reports
@@ -77,5 +77,5 @@ Don't raise a bug report unless it's definitely a bug.
 "I don't like this" or "I didn't expect this to happen" is not the same thing as a bug.
 
 Many unjustified bug reports are filed because people they think it will get them more attention.
-Instead, you may be just wasting maintainer time because we have to reclassify your invalid bug report or convert it to a discussion, and you are much less likely to get the attention you're hoping for.
+Instead, you may be wasting maintainer time because we have to reclassify your invalid bug report or convert it to a discussion, and you are much less likely to get the attention you're hoping for.
 If in doubt, start a discussion instead.
diff --git a/docs/development/local-development.md b/docs/development/local-development.md
index c390be6694..f2ca132412 100644
--- a/docs/development/local-development.md
+++ b/docs/development/local-development.md
@@ -139,8 +139,8 @@ Refactor PRs should ideally not change or remove tests (adding tests is OK).
 
 ### Jest
 
-You can run just the Jest unit tests by running `yarn jest`.
-You can also run just a subset of the Jest tests using file matching, e.g. `yarn jest composer` or `yarn jest workers/repository/update/branch`.
+Run the Jest unit tests with the `yarn jest` command.
+You can also run a subset of the Jest tests using file matching, e.g. `yarn jest composer` or `yarn jest workers/repository/update/branch`.
 If you get a test failure due to a "snapshot" mismatch, and you are sure that you need to update the snapshot, then you can append `-u` to the end.
 e.g. `yarn jest composer -u` would update the saved snapshots for _all_ tests in `**/composer/**`.
 
@@ -201,7 +201,7 @@ Also create documentation for the option in the `docs/usage/configuration-option
 
 ### Chrome's inspect tool
 
-It's really easy to debug Renovate with the help of Chrome's inspect tool.
+You can debug Renovate with Chrome's inspect tool.
 Here's an example:
 
 1. Open `chrome://inspect` in Chrome, then select "Open dedicated DevTools for Node"
@@ -211,7 +211,7 @@ Here's an example:
 
 ### VS Code
 
-You can also debug with VS Code.
+You can also debug Renovate with VS Code.
 Here's an example:
 
 1. In the configuration file, e.g. `config.js` in the root directory of the project, add `token` with your Personal Access Token
diff --git a/docs/development/minimal-reproductions.md b/docs/development/minimal-reproductions.md
index bf3d2c6103..5265496f98 100644
--- a/docs/development/minimal-reproductions.md
+++ b/docs/development/minimal-reproductions.md
@@ -68,7 +68,7 @@ A production repository usually has:
 
 Having lots of "moving parts" makes debugging tricky, because debug break points can be triggered hundreds of times.
 
-When you have lots of custom config for Renovate, it's easy to think that you've found the root cause of the behavior.
+When you have lots of custom config for Renovate, it's hard to find the root cause of the behavior.
 Bugs are often caused by multiple features interacting.
 Reducing the config to a minimum helps us find out exactly which config elements are required to trigger the bug.
 
@@ -84,4 +84,5 @@ After a while, issues without a reproduction may be closed unfixed.
 
 ### "I already described what you need in the issue"
 
-If it's simple then it shouldn't take you much time to commit it to a repo.
+Thank you for describing your issue in detail.
+But we still need a minimal reproduction in a repository, and we'd like you to be the one to make sure it matches both your description as well as expected behavior.
diff --git a/docs/development/triage-guide.md b/docs/development/triage-guide.md
index 01eb2b6faa..d7396f5eb7 100644
--- a/docs/development/triage-guide.md
+++ b/docs/development/triage-guide.md
@@ -18,7 +18,7 @@ Take the following steps on an incoming bug report:
 1. Determine if this is a duplicate of an open issue, if duplicate: link to earlier issue, apply `duplicate` label and close the issue.
 1. Check if the _relevant_ logs are provided. If not apply the `logs:problem` label.
 1. If we need the original poster or somebody else to respond to a query of ours, apply the `status:waiting-on-response` label.
-1. If it's an easy issue for somebody new to Renovate to help us with apply the `good first issue` label.
+1. If it's an easy issue for somebody new to Renovate to help us with: apply the `good first issue` label.
 1. If the issue is hard to fix without outside help apply the `help wanted` label.
 
 ### Triaging feature requests workflow
@@ -31,7 +31,7 @@ Take the following steps on an incoming feature request:
 1. Make a best-effort judgement if this is a reasonable feature to put into Renovate. If in doubt, let the core maintainers decide.
 1. Make an initial judgement of the priority, and add the correct priority label.
 1. If we need the original poster or somebody else to respond to a query of ours, apply the `status:waiting-on-response` label.
-1. If it's an easy feature for somebody new to Renovate to help us with apply the `good first issue` label.
+1. If it's an easy feature for somebody new to Renovate to help us with: apply the `good first issue` label.
 1. If the feature is hard to start work on without outside help apply the `help wanted` label.
 
 ## What a triagist is allowed to do
@@ -50,7 +50,7 @@ If you've been given triage rights, you are allowed to do the following things:
 ## Guidelines for triage workflow
 
 The following are guidelines as we cannot cover all situations.
-Use common sense, and just do your best, and you'll do all right.
+Use common sense, do your best, and you'll do all right.
 Don't be afraid to ask for help.
 
 ### Apply labels to issues
diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md
index c9010b177a..2e0b21d7fe 100644
--- a/docs/usage/configuration-options.md
+++ b/docs/usage/configuration-options.md
@@ -239,7 +239,7 @@ You may choose from these values:
 Platforms may only support _some_ of these merge strategies.
 
 If the chosen automerge strategy is not supported on your platform then Renovate stops automerging.
-In that case just set a supported automerge strategy.
+In that case you'll have to set a supported automerge strategy.
 
 ## automergeType
 
@@ -314,7 +314,7 @@ Configuring this to `true` means that Renovate will detect and apply the default
 By default, Renovate won't enforce any concurrent branch limits.
 The `config:base` preset that many extend from limits the number of concurrent branches to 10, but in many cases a limit as low as 3 or 5 can be most efficient for a repository.
 
-If you want the same limit for both concurrent branches and concurrent PRs, then just set a value for `prConcurrentLimit` and it will be reused for branch calculations too.
+If you want the same limit for both concurrent branches and concurrent PRs, then set a value for `prConcurrentLimit` and it will be re-used for branch calculations too.
 But if you want to allow more concurrent branches than concurrent PRs, you can configure both values (e.g. `branchConcurrentLimit=5` and `prConcurrentLimit=3`).
 
 This limit is enforced on a per-repository basis.
@@ -408,7 +408,7 @@ Important: private submodules aren't supported by Renovate, unless the underlyin
 
 ## commitBody
 
-Configure this if you wish Renovate to add a commit body, otherwise Renovate just uses a regular single-line commit.
+Configure this if you wish Renovate to add a commit body, otherwise Renovate uses a regular single-line commit.
 
 For example, To add `[skip ci]` to every commit you could configure:
 
@@ -637,7 +637,7 @@ Examples of what having a Dependency Dashboard will allow you to do:
 
 <!-- prettier-ignore -->
 !!! tip
-    Just enabling the Dependency Dashboard doesn't change the "control flow" of Renovate.
+    Enabling the Dependency Dashboard by itself does _not_ change the "control flow" of Renovate.
     Renovate still creates and manages PRs, and still follows your schedules and rate limits.
     The Dependency Dashboard gives you extra visibility and control over your updates.
 
@@ -944,7 +944,9 @@ If you are running on any platform except github.com, you need to [configure a P
 `fileMatch` patterns in the user config are added to the default values and do not replace them.
 The default `fileMatch` patterns cannot be removed, so if you need to include or exclude specific paths then use the `ignorePaths` or `includePaths` configuration options.
 
-Sometimes file matches are really simple - for example with Go Modules Renovate looks for any `go.mod` file, and you probably don't need to change that default.
+Some `fileMatch` patterns are short, like Renovate's default Go Modules `fileMatch` for example.
+Here Renovate looks for _any_ `go.mod` file.
+In this case you can probably keep using that default `fileMatch`.
 
 At other times, the possible files is too vague for Renovate to have any default.
 For default, Kubernetes manifests can exist in any `*.yaml` file and we don't want Renovate to parse every single YAML file in every repository just in case some of them have a Kubernetes manifest, so Renovate's default `fileMatch` for manager `kubernetes` is actually empty (`[]`) and needs the user to tell Renovate what directories/files to look in.
@@ -952,7 +954,7 @@ For default, Kubernetes manifests can exist in any `*.yaml` file and we don't wa
 Finally, there are cases where Renovate's default `fileMatch` is good, but you may be using file patterns that a bot couldn't possibly guess about.
 For example, Renovate's default `fileMatch` for `Dockerfile` is `['(^|/|\\.)([Dd]ocker|[Cc]ontainer)file$', '(^|/)([Dd]ocker|[Cc]ontainer)file[^/]*$']`.
 This will catch files like `backend/Dockerfile`, `prefix.Dockerfile` or `Dockerfile-suffix`, but it will miss files like `ACTUALLY_A_DOCKERFILE.template`.
-Because `fileMatch` is mergeable, you don't need to duplicate the defaults and could just add the missing file like this:
+Because `fileMatch` is mergeable, you don't need to duplicate the defaults and could add the missing file like this:
 
 ```json
 {
@@ -1488,9 +1490,9 @@ To adjust it down to 10s for all queries, do this:
 ## ignoreDeprecated
 
 By default, Renovate won't update a dependency version to a deprecated release unless the current version was _itself_ deprecated.
-The goal of this is to make sure you don't upgrade from a non-deprecated version to a deprecated one just because it's higher than the current version.
+The goal of this is to make sure you don't upgrade from a non-deprecated version to a deprecated one, only because it's higher than the current version.
 
-If for some reason you wish to _force_ deprecated updates with Renovate, you can configure `ignoreDeprecated` to `false`, but this is not recommended for most situations.
+If for some reason you wish to _force_ deprecated updates with Renovate, you can configure `ignoreDeprecated` to `false`, which we do not recommend for most situations.
 
 ## ignoreDeps
 
@@ -1595,7 +1597,7 @@ Also check out the `followTag` configuration option above if you wish Renovate t
 
 If you wish for Renovate to process only select paths in the repository, use `includePaths`.
 
-Alternatively, if you need to just _exclude_ certain paths in the repository then consider `ignorePaths` instead.
+Alternatively, if you need to _exclude_ certain paths in the repository then consider `ignorePaths` instead.
 If you are more interested in including only certain package managers (e.g. `npm`), then consider `enabledManagers` instead.
 
 ## internalChecksAsSuccess
@@ -1821,7 +1823,7 @@ Here is an example if you want to group together all packages starting with `esl
 
 Note how the above uses `matchPackagePatterns` with a regex value.
 
-Here is an example where you might want to limit the "noisy" package `aws-sdk` to updates just once per week:
+Here's an example config to limit the "noisy" `aws-sdk` package to weekly updates:
 
 ```json
 {
@@ -1837,7 +1839,7 @@ Here is an example where you might want to limit the "noisy" package `aws-sdk` t
 For Maven dependencies, the package name is `<groupId:artefactId>`, e.g. `"matchPackageNames": ["com.thoughtworks.xstream:xstream"]`
 
 Note how the above uses `matchPackageNames` instead of `matchPackagePatterns` because it is an exact match package name.
-This is the equivalent of defining `"matchPackagePatterns": ["^aws\-sdk$"]` and hence much simpler.
+This is the equivalent of defining `"matchPackagePatterns": ["^aws\-sdk$"]`.
 However you can mix together both `matchPackageNames` and `matchPackagePatterns` in the same package rule and the rule will be applied if _either_ match.
 Example:
 
@@ -2245,7 +2247,7 @@ See also `excludePackagePrefixes`.
 }
 ```
 
-Just like the earlier `matchPackagePatterns` example, the above will configure `rangeStrategy` to `replace` for any package starting with `angular`.
+Like the earlier `matchPackagePatterns` example, the above will configure `rangeStrategy` to `replace` for any package starting with `angular`.
 
 ### matchPaths
 
@@ -2842,7 +2844,7 @@ Renovate won't deliberately "narrow" any range by increasing the semver value in
 For example, if your `package.json` specifies a value for `left-pad` of `^1.0.0` and the latest version on npmjs is `1.2.0`, then Renovate won't change anything because `1.2.0` satisfies the range.
 If instead you'd prefer to be updated to `^1.2.0` in cases like this, then configure `rangeStrategy` to `bump` in your Renovate config.
 
-This feature supports simple caret (`^`) and tilde (`~`) ranges only, like `^1.0.0` and `~1.0.0`.
+This feature supports caret (`^`) and tilde (`~`) ranges only, like `^1.0.0` and `~1.0.0`.
 
 The `in-range-only` strategy may be useful if you want to leave the package file unchanged and only do `update-lockfile` within the existing range.
 The `in-range-only` strategy behaves like `update-lockfile`, but discards any updates where the new version of the dependency is not equal to the current version.
@@ -3484,7 +3486,8 @@ Example:
 Usually, each language or package manager has a specific type of "versioning":
 JavaScript uses npm's SemVer implementation, Python uses pep440, etc.
 
-Renovate also uses custom versioning, like `"docker"` to address the most common way people tag versions using Docker, and `"loose"` as a fallback that tries SemVer first but otherwise just does its best to sort and compare.
+Renovate also uses custom versioning, like `"docker"` to address the most common way people tag versions using Docker, and `"loose"` as a fallback that tries SemVer first.
+Otherwise Renovate does its best to sort and compare.
 
 By exposing `versioning` to config, you can override the default versioning for a package manager if needed.
 We do not recommend overriding the default versioning, but there are some cases such as Docker or Gradle where versioning is not strictly defined and you may need to specify the versioning type per-package.
diff --git a/docs/usage/configuration-templates.md b/docs/usage/configuration-templates.md
index ae35c8b6a8..c995e94079 100644
--- a/docs/usage/configuration-templates.md
+++ b/docs/usage/configuration-templates.md
@@ -29,7 +29,7 @@ Be careful, and consider creating a new "config help" post at the [discussions t
 
 ## Commit Message
 
-Renovate will use one commit per branch, this makes it easy for you to merge.
+Renovate uses one commit per branch.
 The `commitMessage` reflects the contents of the branch and is usually the same as the PR title.
 
 `commitMessage` has a default value of `{{commitMessagePrefix}} {{commitMessageAction}} {{commitMessageTopic}} {{commitMessageExtra}} {{commitMessageSuffix}}`, with the intention that you only edit some of those subcomponents.
@@ -37,7 +37,7 @@ The `commitMessage` reflects the contents of the branch and is usually the same
 You usually don't need to edit `commitMessagePrefix`, this option is used by Renovate if it needs to add a prefix to conform to the Semantic Commit convention.
 Avoid editing the commit message, unless you know what you're doing.
 
-`commitMessageAction` is usually just one word, e.g. 'Update', 'Pin', 'Refresh', etc.
+`commitMessageAction` is usually one word, like 'Update', 'Pin', 'Refresh', etc.
 You're probably fine leaving this setting alone, though you can change it.
 e.g. if you prefer that Renovate uses the term 'Upgrade' instead of 'Update' then you could configure `"commitMessageAction": "Upgrade"`.
 
diff --git a/docs/usage/dependency-pinning.md b/docs/usage/dependency-pinning.md
index 824998c90a..6a8356488c 100644
--- a/docs/usage/dependency-pinning.md
+++ b/docs/usage/dependency-pinning.md
@@ -8,7 +8,7 @@ description: The pros and cons of dependency pinning for JavaScript/npm
 Once you start using a tool/service like Renovate, probably the biggest decision you need to make is whether to "pin" your dependencies instead of using SemVer ranges.
 The answer is "It's your choice", but we can certainly make some generalisations/recommendations to help you.
 
-If you do not want to read the in-depth discussion, and just want our recommendations, skip ahead to the ["So what's best?" section](#so-whats-best).
+If you don't want to read the in-depth discussion, you can skip ahead to our recommendations in the ["So what's best?" section](#so-whats-best).
 
 ## What is Dependency Pinning?
 
@@ -65,7 +65,7 @@ If you were using default caret SemVer ranges, then your `main` branch is now "b
 You would need to manually check and work out which dependency caused the failure (`foobar` may not have been the only dependency to have "automatically" upgraded since the last time your tests passed) and then you would need to pin the dependency yourself to stop `npm` installing `1.2.0`.
 
 Consider the same situation if instead you were _pinning_ dependency versions.
-Your `main` branch would not be broken because it's pinned to `foobar@1.1.0` - instead you'd just have a Pull Request for upgrading to `foobar@1.2.0` which would fail.
+Your `main` branch would not be broken because it's pinned to `foobar@1.1.0` - instead you'd have a Pull Request for upgrading to `foobar@1.2.0` which would fail.
 You'd know not to merge it and can wait for `foobar@1.2.1` or later when it's fixed.
 By pinning dependencies you know exactly what you're running and you know exactly what failed.
 
@@ -135,7 +135,7 @@ To learn all about controlling Renovate's schedule, read the [key concepts, sche
 ### Grouping related packages
 
 Although it's good to isolate each dependency update for ease of troubleshooting, there are times when the extra noise isn't worth it, or when packages naturally belong together anyway (such as all `babel` packages).
-You can add a package rule in our Renovate configuration to group these together and you'll get just one branch combined even if multiple packages have updates available.
+You can add a package rule in our Renovate configuration to group these together and you'll get one branch combined even if multiple packages have updates available.
 
 ## Pinning Dependencies and Lock Files
 
diff --git a/docs/usage/docker.md b/docs/usage/docker.md
index 8576c17649..731ba523fa 100644
--- a/docs/usage/docker.md
+++ b/docs/usage/docker.md
@@ -85,14 +85,14 @@ You probably expect `myimage:1` and `myimage:1.2` to change over time, but you m
 Although it probably _shouldn't_, the reality is that any Docker image tag _can_ change content, and potentially break.
 
 By replacing Docker tags with Docker digests as the image's primary identifier you'll get immutable builds.
-It's hard to work with strings like `FROM node@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`.
-Luckily Renovate can update the digests for you, so you don't have to.
+Working with strings like `FROM node@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e` is hard.
+Luckily Renovate can update the digests for you.
 
-To keep things simple, Renovate keeps the Docker tag in the `FROM` line, like this: `FROM node:14.15.1@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`.
+When pinning a digest, Renovate retains the Docker tag in the `FROM` line for readability, like this: `FROM node:14.15.1@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`.
 
 ## Digest Updating
 
-If you follow our advice to replace a simple tag like `node:14` with a pinned digest `node:14@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`, you will get Renovate PRs whenever the `node:14` image is updated on Docker Hub.
+If you follow our advice to replace a tag like `node:14` with a pinned digest like `node:14@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`, you will get Renovate PRs whenever the `node:14` image is updated on Docker Hub.
 
 Previously this update would have been "invisible" to you - one day you pull code that represents `node:14.15.0` and the next day you pull code that represents `node:14.15.1`.
 But you can never be sure, especially as Docker caches.
@@ -106,8 +106,8 @@ This makes sure everyone on your team uses the latest versions.
 Renovate also supports _upgrading_ versions in Docker tags, e.g. from `myimage:1.2.0` to `myimage:1.2.1` or `myimage:1.2` to `myimage:1.3`.
 If a tag looks like a version, Renovate will upgrade it like a version.
 
-We recommend you use the major.minor.patch tagging scheme, e.g. change from `myimage:1` to `myimage:1.1.1`.
-This way it's easy to see what the Renovate PR is going to change.
+We recommend you use the `major.minor.patch` tagging scheme, e.g. change from `myimage:1` to `myimage:1.1.1`.
+This way you can see what the Renovate PR is going to change.
 You can see the difference between a PR that upgrades `myimage` from `1.1.1` to `1.1.2` and a PR that changes the contents of the version you already use (`1.1.1`).
 
 By default, Renovate will upgrade minor/patch versions (like from `1.2.0` to `1.2.1`), but not upgrade major versions.
diff --git a/docs/usage/examples/self-hosting.md b/docs/usage/examples/self-hosting.md
index 1e6e997f6c..9c48e3363b 100644
--- a/docs/usage/examples/self-hosting.md
+++ b/docs/usage/examples/self-hosting.md
@@ -201,7 +201,7 @@ workflows:
 ### GitLab CI/CD pipeline
 
 For GitLab pipelines we recommend you use the [`renovate-runner` project on GitLab](https://gitlab.com/renovate-bot/renovate-runner).
-We prepared some pipeline templates so its easy to run Renovate on pipeline schedules.
+We created some pipeline templates to help you run Renovate on pipeline schedules.
 You can also find the configuration steps there.
 
 For self-hosted GitLab clone/import the [`renovate-runner` project on GitLab](https://gitlab.com/renovate-bot/renovate-runner) project to your instance.
@@ -314,7 +314,7 @@ metadata:
   namespace: <namespace>
 ```
 
-Then you just need to add Git author, and mount volumes.
+Then you need to add a Git author, and configure the mount volumes.
 The final configuration should look something like this:
 
 ```yml
diff --git a/docs/usage/faq.md b/docs/usage/faq.md
index fcbd189467..dd5a368716 100644
--- a/docs/usage/faq.md
+++ b/docs/usage/faq.md
@@ -57,7 +57,7 @@ When you create a new repository on say GitHub or GitLab, you'll get a `main` br
 
 We replaced `master` with `main` in our documentation where possible.
 
-A branch name has no special meaning within the Git program, it's just a name.
+A branch name has no special meaning within the Git program, it's only a name.
 The base branch could be called `trunk` or `mainline` or `prod`, and Git would work just as well.
 
 ## What if I need to .. ?
diff --git a/docs/usage/getting-started/installing-onboarding.md b/docs/usage/getting-started/installing-onboarding.md
index 7b3275c2ad..5aa5c0d3d7 100644
--- a/docs/usage/getting-started/installing-onboarding.md
+++ b/docs/usage/getting-started/installing-onboarding.md
@@ -13,7 +13,7 @@ Otherwise, the process for adding new repositories to a Renovate installation ca
 
 ### Hosted GitHub.com App
 
-Installing/enabling Mend's Renovate GitHub App is simple.
+Follow these steps to install and enable Mend's Renovate GitHub App:
 
 First, navigate to [https://github.com/apps/renovate](https://github.com/apps/renovate) and select the Install button:
 
diff --git a/docs/usage/getting-started/private-packages.md b/docs/usage/getting-started/private-packages.md
index 3fd93fbef6..5caa427c86 100644
--- a/docs/usage/getting-started/private-packages.md
+++ b/docs/usage/getting-started/private-packages.md
@@ -155,7 +155,7 @@ It can be confusing for people who host their own source code privately to be as
 
 Currently the preferred way to configure `github.com` credentials for self-hosted Renovate is:
 
-- Create a read-only Personal Access Token (PAT) for a `github.com` account. This can be any GitHub account, it might be better to create an "empty" account just for this purpose.
+- Create a read-only Personal Access Token (PAT) for a `github.com` account. This can be any GitHub account, but we recommend you create an "empty" account for this purpose.
 - Add the PAT to Renovate using the environment variable `GITHUB_COM_TOKEN`
 
 ## Package Manager Credentials for Artifact Updating
@@ -286,7 +286,7 @@ This merge approach is similar to how `npm` itself behaves if `.npmrc` is found
 
 #### Add npmToken to Renovate config
 
-If you are using the main npmjs registry then you can configure just the `npmToken` instead:
+If you are using the main npmjs registry then you can configure only the `npmToken` instead:
 
 ```json
 {
diff --git a/docs/usage/key-concepts/automerge.md b/docs/usage/key-concepts/automerge.md
index 4df1b7f68c..b63a0af9cb 100644
--- a/docs/usage/key-concepts/automerge.md
+++ b/docs/usage/key-concepts/automerge.md
@@ -18,7 +18,7 @@ Renovate's approach is to ensure that automerging branches are up-to-date with t
 This means merging multiple branches in a row won't work reliably, so we prefer not to do that.
 What all this means is that Renovate will only automerge at most one branch/PR per target branch per run, before you need to wait for the next run.
 
-As a general guide, we recommend that you enable automerge for any type of dependency updates where you would just select "merge" anyway.
+As a general guide, we recommend that you enable automerge for any type of dependency updates where you would select "merge" anyway.
 For any updates where you want to review the release notes - or code - before you merge, you can keep automerge disabled.
 
 Automerge works particularly well for `devDependencies` as well as for production `dependencies` in projects which have great test coverage.
diff --git a/docs/usage/key-concepts/presets.md b/docs/usage/key-concepts/presets.md
index 778d3f288f..d9906d7f12 100644
--- a/docs/usage/key-concepts/presets.md
+++ b/docs/usage/key-concepts/presets.md
@@ -39,7 +39,8 @@ This way you have all global configuration in a single file, in a single reposit
 
 ## Presets are modular
 
-Preset configs are modular, they can be as small as a single package rule or as large as an entire configuration, just like an ESLint config.
+Preset configs are modular, they can be as small as a single package rule or as large as an entire configuration.
+This is similar to the way you can share ESLint configurations.
 
 ## Built-in presets
 
diff --git a/docs/usage/key-concepts/pull-requests.md b/docs/usage/key-concepts/pull-requests.md
index 75164c5fd9..4f63045a5f 100644
--- a/docs/usage/key-concepts/pull-requests.md
+++ b/docs/usage/key-concepts/pull-requests.md
@@ -46,7 +46,7 @@ This document explains why we have immortal PRs, and how you can fix them.
 ### Why we have immortal PRs
 
 First off, we don't have immortal PRs for some philosphical reason like: "don't ignore this update, it's good for you!".
-We just have no way to ignore some PRs after they're closed.
+We have no good way to ignore some PRs after they're closed.
 
 #### Branch name and PR title are cache keys
 
@@ -84,10 +84,10 @@ Instead, set `"dependencyDashboardApproval": true` for major updates so that you
 
 ## Ignoring PRs
 
-To ignore a PR you just close it unmerged.
+Close a Renovate PR to ignore it.
 
 <!-- prettier-ignore -->
 !!! note
-    Renovate will re-create any PRs that is marked "immortal".
-    What this means is that any immortal PR you close, will pop up again the next time Renovate runs.
+    Renovate re-creates any PRs that are marked "immortal".
+    This means that any immortal PR you close, pops up again the next time Renovate runs.
     To ignore immortal PRs, follow the advice in the [How to fix immortal PRs](#how-to-fix-immortal-prs) section.
diff --git a/docs/usage/known-limitations.md b/docs/usage/known-limitations.md
index c57b5015c9..60d186d672 100644
--- a/docs/usage/known-limitations.md
+++ b/docs/usage/known-limitations.md
@@ -13,7 +13,7 @@ This document tries to list out the most commonly seen limitations and describe
 ## Time/schedule based limitations
 
 When a user configures a schedule in their repo config, they may think that this schedule "controls" when Renovate runs.
-In actuality, Renovate may be running frequently, but just skipping updates to the repo if the configured schedule is not met.
+In actuality, Renovate may be running frequently, but skipping updates to the repo if the configured schedule is not met.
 Additionally, the Renovate admin may have put the bot on its own schedule, or the job queue may be too long, so Renovate doesn't even get a chance to run on your repository during a certain scheduled time window.
 
 For scheduled action to take place, both these need to happen:
diff --git a/docs/usage/noise-reduction.md b/docs/usage/noise-reduction.md
index 6132878cdf..1fc3331c18 100644
--- a/docs/usage/noise-reduction.md
+++ b/docs/usage/noise-reduction.md
@@ -123,7 +123,7 @@ Granularity must be at least one hour.
 Automerging is a Renovate feature that can save you a lot of time/noise directly, while also benefiting grouping and scheduling.
 In short: it means that Renovate can merge PRs or even branches itself if they pass your tests.
 
-We recommend that you enable automerge for any type of dependency update where you would just select Merge anyway.
+We recommend that you enable automerge for any type of dependency update where you would select Merge anyway.
 We all know that there are some types of updates that we (nearly) always verify manually before merging, and plenty of others that we don't bother looking at unless tests fail.
 Every time you select Merge on a Renovate PR without manually testing it, you should consider if you can enable automerge and save yourself the time in future.
 
diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md
index fcf72c943a..fc162fb95c 100644
--- a/docs/usage/self-hosted-configuration.md
+++ b/docs/usage/self-hosted-configuration.md
@@ -299,7 +299,7 @@ Periods (`.`) in host names must be replaced with a single underscore (`_`).
 
 ### Datasource and credentials only
 
-You can skip the host part, and use just the datasource and credentials.
+You can skip the host part, and use only the datasource and credentials.
 
 `DOCKER_USERNAME=bot DOCKER_PASSWORD=botpass123`:
 
@@ -590,7 +590,7 @@ Default is no limit.
 This private key is used to decrypt config files.
 
 The corresponding public key can be used to create encrypted values for config files.
-If you want a simple UI to encrypt values you can put the public key in a HTML page similar to <https://app.renovatebot.com/encrypt>.
+If you want a UI to encrypt values you can put the public key in a HTML page similar to <https://app.renovatebot.com/encrypt>.
 
 To create the key pair with GPG use the following commands:
 
@@ -659,7 +659,9 @@ Instead, with scoped secrets it means that Renovate ensures that the organizatio
 
 <!-- prettier-ignore -->
 !!! note
-    Simple public key encryption was previously used to encrypt secrets, but this approach has been deprecated and is no longer documented.
+    You could use public key encryption with earlier versions of Renovate.
+    We deprecated this approach and removed the documentation for it.
+    If you're _still_ using public key encryption then we recommend that you use private keys instead.
 
 ## privateKeyOld
 
diff --git a/lib/modules/manager/argocd/readme.md b/lib/modules/manager/argocd/readme.md
index 65f7028a33..d954606bc7 100644
--- a/lib/modules/manager/argocd/readme.md
+++ b/lib/modules/manager/argocd/readme.md
@@ -1,4 +1,5 @@
-The `argocd` manager has no `fileMatch` default patterns, so it won't match any files until you configure it with a pattern. This is because there is no commonly accepted file/directory naming convention for argocd YAML files and we don't want to check every single `*.yaml` file in repositories just in case any of them have ArgoCD definitions.
+The `argocd` manager has no `fileMatch` default patterns, so it won't match any files until you configure it with a pattern.
+This is because there is no commonly accepted file/directory naming convention for argocd YAML files and we don't want to check every single `*.yaml` file in repositories just in case any of them have ArgoCD definitions.
 
 If most `.yaml` files in your repository are argocd ones, then you could add this to your config:
 
@@ -20,7 +21,7 @@ If instead you have them all inside a `argocd/` directory, you would add this:
 }
 ```
 
-Or if it's just a single file then something like this:
+Or if it's only a single file then something like this:
 
 ```json
 {
diff --git a/lib/modules/manager/kubernetes/readme.md b/lib/modules/manager/kubernetes/readme.md
index 96dc8fc6a5..10632560e0 100644
--- a/lib/modules/manager/kubernetes/readme.md
+++ b/lib/modules/manager/kubernetes/readme.md
@@ -1,4 +1,5 @@
-The `kubernetes` manager has no `fileMatch` default patterns, so it won't match any files until you configure it with a pattern. This is because there is no commonly accepted file/directory naming convention for Kubernetes YAML files and we don't want to check every single `*.yaml` file in repositories just in case any of them have Kubernetes definitions.
+The `kubernetes` manager has no `fileMatch` default patterns, so it won't match any files until you configure it with a pattern.
+This is because there is no commonly accepted file/directory naming convention for Kubernetes YAML files and we don't want to check every single `*.yaml` file in repositories just in case any of them have Kubernetes definitions.
 
 If most `.yaml` files in your repository are Kubernetes ones, then you could add this to your config:
 
@@ -20,7 +21,7 @@ If instead you have them all inside a `k8s/` directory, you would add this:
 }
 ```
 
-Or if it's just a single file then something like this:
+Or if it's only a single file then something like this:
 
 ```json
 {
diff --git a/lib/modules/manager/regex/readme.md b/lib/modules/manager/regex/readme.md
index 90ae7965db..de29204879 100644
--- a/lib/modules/manager/regex/readme.md
+++ b/lib/modules/manager/regex/readme.md
@@ -131,8 +131,6 @@ The `Dockerfile` is documented better as well.
 The syntax in the example is arbitrary, and you can set your own syntax.
 If you do, update your `matchStrings` regex!
 
-You can use simple versions of such comments to increase readability.
-
 For example the `appVersion` property in a `Chart.yaml` of a Helm chart is always referenced to an Docker image.
 In such scenarios, some values can be hard-coded.
 For example:
diff --git a/lib/modules/versioning/loose/readme.md b/lib/modules/versioning/loose/readme.md
index 8c036d60b4..ea24d00e39 100644
--- a/lib/modules/versioning/loose/readme.md
+++ b/lib/modules/versioning/loose/readme.md
@@ -1 +1,3 @@
-Renovate's "loose" versioning was created for cases where no strict versioning is in place. It works like SemVer if SemVer-compliant versions are supplied, but otherwise is "best effort". Essentially it just does its best to sort versions and ignore versions that are not sortable.
+Renovate's "loose" versioning was created for cases where no strict versioning is in place.
+It works like SemVer if SemVer-compliant versions are supplied, but otherwise is "best effort".
+Essentially "loose" versioning does its best to sort versions and ignores "unsortable" versions.
-- 
GitLab