Update explanation about the `extends` feature

1 files changed, 12 insertions, 4 deletions

diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 15dde36cca8..8b770495853 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -102,10 +102,13 @@ rspec:
       - $RSPEC
 ```
 
-In the example above, the `rspec` job is going to inherit from the `.tests`
-template job. GitLab will perform a reverse deep merge, which means that it will
-merge the `rspec` contents into `.tests` recursively, and this is going to result in
-the following `rspec` job:
+In the example above, the `rspec` job inherits from the `.tests` template job. 
+GitLab will perform a reverse deep merge based on the keys. GitLab will:
+
+- Merge the `rspec` contents into `.tests` recursively.
+- Not merge the values of the keys.
+
+This results in the following `rspec` job:
 
 ```yaml
 rspec:
@@ -118,6 +121,11 @@ rspec:
       - $RSPEC
 ```
 
+NOTE: **Note:**
+Note that `script: rake test` has been overwritten by `script: rake rspec`.
+
+If you do want to include the `rake test`, have a look at [before_script-and-after_script](#before_script-and-after_script).
+
 `.tests` in this example is a [hidden key](#hidden-keys-jobs), but it's
 possible to inherit from regular jobs as well.