docs: improve self-hosting documentation (#8079)

docs/usage/self-hosting.md

@@ -2,25 +2,26 @@
 
 ## Installing Renovate OSS CLI
 
-#### npmjs
+### npmjs
 
 ```sh
 $ npm install -g renovate
 ```
 
-Since renovate v20 `npm`, `pnpm` and `yarn` are no longer embedded, so you need to install them globally if you need to update lockfiles.
+Renovate does not embed `npm`, `pnpm` and `yarn` as its own dependencies.
+If you want to use these package managers to update your lockfiles, you must ensure that the correct versions are already installed globally.
 
 ```sh
 $ npm install -g yarn pnpm
 ```
 
-The same goes for any other third party binary tool that may be needed, such as `gradle` or `poetry` - you need to make sure they are installed and the appropriate version you need before running Renovate.
+The same goes for any other third party binary tool like `gradle` or `poetry` - you need to make sure they are installed and the appropriate version before running Renovate.
 
-#### Docker
+### Docker
 
 Renovate is available for Docker via an automated build [renovate/renovate](https://hub.docker.com/r/renovate/renovate/).
 It builds `latest` based on the `master` branch and all semver tags are published too.
-All the following are valid:
+For example, all the following are valid tags:
 
 ```sh
 $ docker run --rm renovate/renovate
@@ -29,16 +30,17 @@ $ docker run --rm renovate/renovate:24.14
 $ docker run --rm renovate/renovate:24
 ```
 
-(Please look up what the latest actual tags are though, do not use the above literally).
+Do not use the example tags listed above, as they will be out-of-date.
+Go to [renovate/renovate tags](https://hub.docker.com/r/renovate/renovate/tags) to grab the latest tagged release from Renovate.
 
-If you wish to configure Renovate using a `config.js` file then map it to `/usr/src/app/config.js` using Docker volumes.
+If you want to configure Renovate using a `config.js` file then map it to `/usr/src/app/config.js` using Docker volumes.
 For example:
 
 ```sh
 $ docker run --rm -v "/path/to/your/config.js:/usr/src/app/config.js" renovate/renovate
 ```
 
-#### Kubernetes
+### Kubernetes
 
 Renovate's official Docker image is compatible with Kubernetes.
 The following is an example manifest of running Renovate against a GitHub Enterprise server.
@@ -80,7 +82,7 @@ metadata:
 type: Opaque
 stringData:
   GITHUB_COM_TOKEN: 'any-personal-user-token-for-github-com-for-fetching-changelogs'
-  # set to true to run on all repos you have push access to
+  # You can set RENOVATE_AUTODISCOVER to true to run Renovate on all repos you have push access to
   RENOVATE_AUTODISCOVER: 'false'
   RENOVATE_ENDPOINT: 'https://github.company.com/api/v3'
   RENOVATE_GIT_AUTHOR: 'Renovate Bot <bot@renovateapp.com>'
@@ -88,7 +90,7 @@ stringData:
   RENOVATE_TOKEN: 'your-github-enterprise-renovate-user-token'
 ```
 
-A `config.js` file can be added to the manifest using a `ConfigMap` as shown in the following example (using a "dry run" in github.com)
+A `config.js` file can be added to the manifest using a `ConfigMap` as shown in the following example (using a "dry run" in github.com):
 
 ```yaml
 ---
@@ -144,7 +146,7 @@ spec:
               emptyDir: {}
 ```
 
-#### CircleCI
+### CircleCI
 
 If you are using CircleCI, you can use the third-party [daniel-shuy/renovate](https://circleci.com/developer/orbs/orb/daniel-shuy/renovate) orb to run a self-hosted instance of Renovate on CircleCI.
 
@@ -160,7 +162,7 @@ The following example runs Renovate hourly, and looks for the self-hosted config
 ```yml
 version: '2.1'
 orbs:
-  renovate: daniel-shuy/renovate@2.1
+  renovate: daniel-shuy/renovate@2.1.1
 workflows:
   renovate:
     jobs:
@@ -176,7 +178,7 @@ workflows:
                   - master
 ```
 
-#### GitLab CI/CD pipeline
+### 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've prepared some pipeline templates to run Renovate on pipeline schedules in an easy way.
@@ -189,8 +191,8 @@ For self-hosted GitLab clone/import the [renovate-runner](https://gitlab.com/ren
 Self-hosted Renovate can be configured using any of the following (or a combination):
 
 - A `config.js` file (can also be named `config.json`, but you can't have both at the same time)
-- CLI params
-- Environment params
+- CLI parameters
+- Environment parameters
 
 Note that some Renovate configuration options are _only_ available for self-hosting, and so can only be configured using one of the above methods.
 These are described in the [Self-hosted Configuration](./self-hosted-configuration.md) doc.
@@ -201,32 +203,32 @@ Regardless of platform, you need to select a user account for `renovate` to assu
 It is recommended to be `@renovate-bot` if you are using a self-hosted server with free choice of usernames.
 It is also recommended that you configure `config.gitAuthor` with the same identity as your Renovate user, e.g. like `"gitAuthor": "Renovate Bot <renovate@whitesourcesoftware.com>"`.
 
-#### GitHub Enterprise
+### GitHub Enterprise
 
 First, [create a personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) for the bot account (select "repo" permissions).
 Configure it either as `token` in your `config.js` file, or in environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.
 
-#### GitLab CE/EE
+### GitLab CE/EE
 
 First, [create a personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) for the bot account (select `read_user`, `api` and `write_repository` scopes).
 Configure it either as `token` in your `config.js` file, or in environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.
 Don't forget to configure `platform=gitlab` somewhere in config.
 
-#### Bitbucket Cloud
+### Bitbucket Cloud
 
 First, [create an AppPassword](https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html) for the bot account.
 Configure it as `password` in your `config.js` file, or in environment variable `RENOVATE_PASSWORD`, or via CLI `--password=`.
 Also be sure to configure the `username` for your bot account too.
 Don't forget to configure `platform=bitbucket` somewhere in config.
 
-#### Bitbucket Server
+### Bitbucket Server
 
 Create a [Personal Access Token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) for your bot account.
 Configure it as `password` in your `config.js` file, or in environment variable `RENOVATE_PASSWORD`, or via CLI `--password=`.
 Also configure the `username` for your bot account too, if you decided not to name it `@renovate-bot`.
 Don't forget to configure `platform=bitbucket-server` somewhere in config.
 
-#### Azure DevOps
+### Azure DevOps
 
 First, [create a personal access token](https://docs.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/pats) for the bot account.
 Configure it either as `token` in your `config.js` file, or in environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.
@@ -245,19 +247,23 @@ This account can actually be _any_ account on GitHub, and needs only read-only a
 It's used when fetching release notes for repositories in order to increase the hourly API limit.
 It's also OK to configure the same as a host rule instead, if you prefer that.
 
-**Note:** If you're using renovate in a project where dependencies are loaded from github.com (such as Go m=Modules hosted on GitHub) it is highly recommended to add a token as you will run in the rate limit from the github.com API, which will lead to renovate closing and reopening PRs because it could not get reliable info on updated dependencies.
+**Note:** If you're using Renovate in a project where dependencies are loaded from github.com (such as Go modules hosted on GitHub) it is highly recommended to add a token as you will run in the rate limit from the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies.
 
 ## File/directory usage
 
-By default, Renovate will store all files within a `renovate/` subdirectory of the operating system's temporary directory, e.g. `/tmp/renovate/`.
+By default, Renovate stores all files in the `renovate/` subdirectory of the operating system's temporary directory, e.g. `/tmp/renovate/`.
 
-Repository data will be copied or cloned into unique subdirectories under `repos/`, e.g. `/tmp/renovate/repos/github/owner1/repo-a/`.
+Repository data is copied or cloned into unique subdirectories under `repos/`, e.g. `/tmp/renovate/repos/github/owner1/repo-a/`.
 
-Cache data - such as Renovate's own cache as well as that for npm, Yarn, Composer, etc - will be stored in `/tmp/renovate/cache`.
+Renovate's own cache, as well as the caches(s) for npm, Yarn, Composer etc, is stored in `/tmp/renovate/cache`.
 
-If you wish to override the base directory to be used (e.g. instead of `/tmp/renovate/`) then configure a value for `baseDir` in `config.js`, or via env (`RENOVATE_BASE_DIR`) or via CLI (`--base-dir=`).
+To use another directory as the base directory, instead of `tmp/renovate`:
 
-If you wish to override the cache location specifically then configure a value for `cacheDir` instead.
+- Configure a value for `baseDir` in `config.js`
+- Use an environment variable `RENOVATE_BASE_DIR`
+- Use the CLI to pass a base directory: `--base-dir=`
+
+If you want to override the cache location then configure a value for `cacheDir` instead.
 
 ## Usage
 
@@ -289,7 +295,8 @@ If running against GitHub Enterprise, change the above `gitlab` values to the eq
 
 You can save this file as anything you want and then use `RENOVATE_CONFIG_FILE` env variable to tell Renovate where to find it.
 
-Most people will run Renovate via cron, e.g. once per hour. Here is an example bash script that you can point `cron` to:
+Most people will run Renovate via cron, e.g. once per hour.
+Here is an example bash script that you can point `cron` to:
 
 ```sh
 #!/bin/bash