Complete rewrite of the documentation of overlays after Jim's additional comments.

[ci skip]

1 files changed, 12 insertions, 13 deletions

diff --git a/dev/ci/user-overlays/README.md b/dev/ci/user-overlays/README.md
index 8cbe8fc33..aec2dfe0a 100644
--- a/dev/ci/user-overlays/README.md
+++ b/dev/ci/user-overlays/README.md
@@ -1,18 +1,17 @@
 # Add overlays for your pull requests in this directory
 
-When your pull request breaks an external development we test in our CI, you
-must prepare a patch (or ask someone to prepare a patch) to fix this development.
-Backward compatible patches are to be preferred, especially on libraries (it is
-harder to make backward compatible patches for plugins).
-
-Once you have a patched version, you can add an overlay to your pull request:
-this is a file which defines where to look for the patched version so that
-testing is possible. It changes the value of some variables from
-[`ci-basic-overlay.sh`](/dev/ci/ci-basic-overlay.sh) (generally both the
-`_CI_BRANCH` and the `_CI_GITURL` variables of a given development at once).
-
-The file contains very simple logic to test the pull request number or branch
-name and apply it only in this case.
+When your pull request breaks an external project we test in our CI and you
+have prepared a branch with the fix, you can add an "overlay" to your pull
+request to test it with the adapted version of the external project.
+
+An overlay is a file which defines where to look for the patched version so that
+testing is possible. It redefines some variables from
+[`ci-basic-overlay.sh`](/dev/ci/ci-basic-overlay.sh):
+give the name of your branch using a `_CI_BRANCH` variable and the location of
+your fork using a `_CI_GITURL` variable.
+
+Moreover, the file contains very simple logic to test the pull request number
+or branch name and apply it only in this case.
 
 The name of your overlay file should start with a five-digit pull request
 number, followed by a dash, anything (for instance your GitHub nickname