Improve secrets documentation (#2707)

Adds some editorial improvements that hopefully clarify the usage of
secrets.

Fixes #2704

---------

Co-authored-by: Michael Holtermann <michael.holtermann@lynq.tech>

docs/docs/20-usage/40-secrets.md

@@ -2,8 +2,6 @@
 
 Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the pipeline at runtime.
 
-Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline.
-
 Woodpecker provides three different levels to add secrets to your pipeline. The following list shows the priority of the different levels. If a secret is defined in multiple levels, will be used following this priorities: Repository secrets > Organization secrets > Global secrets.
 
 1. **Repository secrets**: They are available to all pipelines of an repository.
@@ -13,6 +11,11 @@ Woodpecker provides three different levels to add secrets to your pipeline. The
 
 ## Usage
 
+### Use secrets in commands
+
+Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline,
+once their usage is declared in the `secrets` section:
+
 ```diff
 steps:
   docker:
@@ -23,8 +26,10 @@ steps:
 +   secrets: [ docker_username, docker_password ]
 ```
 
+### Use secrets in settings
+
 Alternatively, you can get a `setting` from secrets using the `from_secret` syntax.
-In this example, the secret named `secret_token` would be passed to the pipeline as `PLUGIN_TOKEN`.
+In this example, the secret named `secret_token` would be passed to the setting named `token`, which will be available in the plugin as environment variable named `PLUGIN_TOKEN`. See [Plugins](./plugins/sample-plugin#write-the-logic) for details.
 
 **NOTE:** the `from_secret` syntax only works with the newer `settings` block.
 
@@ -37,6 +42,8 @@ steps:
 +       from_secret: secret_token
 ```
 
+### Note about parameter pre-processing
+
 Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped.
 
 ```diff
@@ -51,11 +58,7 @@ steps:
     secrets: [ docker_username, docker_password ]
 ```
 
-## Adding Secrets
-
-Secrets are added to the Woodpecker in the UI or with the CLI.
-
-## Alternate Names
+### Alternate Names
 
 There may be scenarios where you are required to store secrets using alternate names. You can map the alternate secret name to the expected name using the below syntax:
 
@@ -70,28 +73,21 @@ steps:
 +       target: docker_password
 ```
 
-## Pull Requests
+### Use in Pull Requests events
 
-Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type.
+Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type, either in UI or by CLI, see below.
 
-```diff
-woodpecker-cli secret add \
-  -repository octocat/hello-world \
-  -image plugins/docker \
-+ -event pull_request \
-+ -event push \
-+ -event tag \
-  -name docker_username \
-  -value <value>
-```
-
-Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets.
+**NOTE:** Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets.
 
 ## Image filter
 
 To prevent abusing your secrets from malicious usage, you can limit a secret to a list of images. If enabled they are not available to any other plugin (steps without user-defined commands). If you or an attacker defines explicit commands, the secrets will not be available to the container to prevent leaking them.
 
-## CLI Examples
+## Adding Secrets
+
+Secrets are added to the Woodpecker in the UI or with the CLI.
+
+### CLI Examples
 
 Create the secret using default settings. The secret will be available to all images in your pipeline, and will be available to all push, tag, and deployment events (not pull request events).