docs: improve config presets (#7796)

docs/usage/config-presets.md

@@ -5,8 +5,8 @@ description: Renovate's support for ESLint-like shareable configs
 
 # Shareable Config Presets
 
-Renovate's "config presets" are a convenient way to distribute config that is reused across multiple repositories.
-It is similar in design to `eslint`'s shareable configs, and can be used both for whole repository configs as well as for individual rules.
+Renovate's "config presets" are a convenient way to distribute config for reuse across multiple repositories.
+It is similar in design to `eslint`'s shareable configs, and can be used for whole repository configs and for individual rules.
 They are defined using the `extends` array within config and may also be nested.
 
 In short:
@@ -16,35 +16,31 @@ In short:
 
 ## Goals of Preset Configs
 
-The main reason for supporting preset configs is to decrease duplication:
+The main reason for supporting preset configs is to decrease duplication.
+By using a preset config you:
 
-1.  You shouldn't need copy/paste the same config across all your repositories
-2.  You shouldn't need to reinvent any config "wheels" that others have invented before
+1. Avoid duplicating the same config across all your repositories
+2. Can use someone else's configuration and extend it
 
-A further reason was to make Renovate configuration "self-documenting", by adding the `"description"` field to all preset configs.
+Renovate's configuration is self-documenting, because you can fill in the `"description"` field in all preset configs.
 
 ## Implementation Approach
 
-In order to achieve the above goals, preset configs have been implemented to allow a very modular approach - preset configs may be as small as a partial package rule or as extensive as an entire configuration, like an `eslint` config.
+In order to achieve these goals, preset configs allow for a very modular approach - preset configs can be as small as a partial package rule or as large as an entire configuration, like an `eslint` config.
 
 ## Preset Hosting
 
-Presets can be defined using either npm packages, or with GitHub/GitLab repositories. Bitbucket-hosted presets are yet to be implemented.
-
-The following namespace is used:
-
-- `abc`: npm package `renovate-config-abc` and preset `default`
-- `@abc`: npm package `@abc/renovate-config` and preset `default`
-- `abc:xyz`: npm package `renovate-config-abc` and preset `xyz`
-- `@abc:xyz`: npm package `@abc/renovate-config` and preset `xyz`
-- `github>abc/foo`: github repository `https://github.com/abc/foo` and preset `default`
-- `github>abc/foo:xyz`: github repository `https://github.com/abc/foo` and preset `xyz`
-- `gitlab>abc/foo`: gitlab repository `https://gitlab.com/abc/foo` and preset `default`
-- `gitlab>abc/foo:xyz`: gitlab repository `https://gitlab.com/abc/foo` and preset `xyz`
-
 In general, GitHub or GitLab-based preset hosting is easier than npm because you avoid the "publish" step - simply commit preset code to the default branch and it will be picked up by Renovate the next time it runs.
 An additional benefit of using source code hosting is that the same token/authentication can be reused by Renovate in case you want to make your config private.
 
+| name                    | example use          | preset    | resolves as                          | filename                          |
+| ----------------------- | -------------------- | --------- | ------------------------------------ | --------------------------------- |
+| GitHub default          | `github>abc/foo`     | `default` | `https://github.com/abc/foo`         | `default.json` or `renovate.json` |
+| GitHub with preset name | `github>abc/foo:xyz` | `xyz`     | `https://github.com/abc/foo`         | `xyz.json`                        |
+| GitLab default          | `gitlab>abc/foo`     | `default` | `https://gitlab.com/abc/foo`         | `default.json` or `renovate.json` |
+| GitLab with preset name | `gitlab>abc/foo:xyz` | `xyz`     | `https://gitlab.com/abc/foo`         | `xyz.json`                        |
+| Local default           | `local>abc/foo`      | `default` | `https://github.company.com/abc/foo` | `default.json` or `renovate.json` |
+
 ## Example configs
 
 An example of a small rule is `:preserveSemverRanges`, which has the description "Preserve (but continue to upgrade) any existing semver ranges".
@@ -54,14 +50,14 @@ An example of a full config is `config:base`, which is Renovate's default config
 It mostly uses Renovate config defaults but adds a few smart customisations such as grouping monorepo packages together.
 
 Special note: the `:xyz` naming convention (with `:` prefix) is a special shorthand for the `default:` presets.
-i.e. `:xyz` is equivalent to `default:xyz`.
+e.g. `:xyz` is equivalent to `default:xyz`.
 
 ## How to Use Preset Configs
 
 By default, the Renovate App's onboarding process will suggest `["config:base]"`.
-If you are self hosting then you must add `"onboardingConfig": { "extends": ["config:base"] }` to your bot's config.
+If you are self hosting you must add `"onboardingConfig": { "extends": ["config:base"] }` to your bot's config.
 
-A typical onboarding `renovate.json` will then look like this:
+A typical onboarding `renovate.json` looks like this:
 
 ```json
 {
@@ -69,8 +65,8 @@ A typical onboarding `renovate.json` will then look like this:
 }
 ```
 
-Let's say you wish to modify that default behaviour, such as to schedule Renovate to process upgrades only during non-office hours.
-In that case you could modify the default `renovate.json` to be like this:
+Say you want to modify the default behaviour, for example scheduling Renovate to process upgrades during non-office hours only.
+To do this you can modify the default `renovate.json` file like this:
 
 ```json
 {
@@ -79,11 +75,11 @@ In that case you could modify the default `renovate.json` to be like this:
 ```
 
 This makes use of the `schedules:` presets.
-To see all presets published by the Renovate team then browse the "Config Presets" section of [Renovate Docs](https://docs.renovatebot.com).
+You can find the Renovate team's preset configs at the "Config Presets" section of [Renovate Docs](https://docs.renovatebot.com).
 
 ## Preset Parameters
 
-If you browse the "default" presets, you will see some that contain parameters, example:
+If you browse the "default" presets, you will see some that contain parameters, e.g.:
 
 ```json
     "labels": {
@@ -110,10 +106,11 @@ Here is how you would use these in your Renovate config:
   ]
 ```
 
-In short, the number of `{{argx}}` params in the definition is how many parameters you need to provide.
+In short, the number of `{{argx}}` parameters in the definition is how many parameters you need to provide.
 Parameters must be strings, non-quoted, and separated by commas if there are more than one.
 
-If you find that you are repeating config a lot, you might consider publishing one of these types of parameterised presets yourself, or if you think your preset would be valuable for others, please contribute a PR to the Renovate repository.
+If you find that you are repeating config a lot, you might consider publishing one of these types of parameterised presets yourself.
+Or if you think your preset would be valuable for others, please contribute a PR to the Renovate repository.
 
 ## How to Publish Preset Configs
 
@@ -185,7 +182,7 @@ To host your preset config on GitLab:
 
 ## Local presets
 
-Renovate also supports local presets, i.e. presets that are hosted on the same platform as the target repository.
+Renovate also supports local presets, e.g. presets that are hosted on the same platform as the target repository.
 This is especially helpful in self-hosted scenarios where public presets cannot be used.
 Local presets are only supported on GitHub, GitLab and Bitbucket Server.
 Local presets are specified either by leaving out any prefix, e.g. `owner/name`, or explicitly by adding a `local>` prefix, e.g. `local>owner/name`.
@@ -198,7 +195,7 @@ You want to configure the encrypted token just once, which means in the preset.
 But you also probably want the preset to be private too, so how can the other repos reference it?
 
 The answer is to host your preset using GitHub or GitLab - not npmjs - and make sure you have added the preset's repo to Renovate too.
-GitHub will then permit Renovate to access the preset repo whenever it is processing any other repos within the same account/org.
+GitHub will then allow Renovate to access the preset repo whenever it is processing any other repos within the same account/org.
 
 ## Contributing to presets
 
@@ -213,7 +210,7 @@ It looks for:
 - A repository called `renovate-config` under the same user/group/org with either `default.json` or `renovate.json`, or
 - A repository named like `.{{platform}}` (e.g. `.github`) under the same user/group/org with `renovate-config.json`
 
-If found, that repository's preset will be suggested as the the sole extended preset, and any existing `onboardingConfig` config will be ignored/overridden.
+If found, that repository's preset will be suggested as the sole extended preset, and any existing `onboardingConfig` config will be ignored/overridden.
 For example the result may be:
 
 ```json