Edit after script context text

2 files changed, 20 insertions, 14 deletions

diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md
index 7d3f39a8c19..b5296f26269 100644
--- a/doc/ci/variables/where_variables_can_be_used.md
+++ b/doc/ci/variables/where_variables_can_be_used.md
@@ -89,13 +89,14 @@ Supported:
   - In `script`, it will work in the following lines of `script`.
   - In `after_script`, it will work in following lines of `after_script`.
 
-Please notice the specific case of `after_script` scripts, that can:
+In the case of `after_script` scripts, they can:
 
-- Only use variables defined before the script within the same `after_script` section.
+- Only use variables defined before the script within the same `after_script`
+  section.
 - Not use variables defined in `before_script` and `script`.
 
-Both restrictions are caused by the fact, that `after_script` script is executed in a
-[separated shell context](https://docs.gitlab.com/ee/ci/yaml/README.html#before_script-and-after_script).
+These restrictions are because `after_script` scripts are executed in a
+[separated shell context](../yaml/README.md#before_script-and-after_script).
 
 ## Persisted variables
 
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index b3aa1bcfad2..4c170056a49 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -215,20 +215,25 @@ This can be an array or a multi-line string.
 `after_script` is used to define the command that will be run after all
 jobs, including failed ones. This has to be an array or a multi-line string.
 
-Script specified in `before_script` is:
+Scripts specified in `before_script` are:
 
-- Concatenated with script specified in the main `script`. Job-level `before_script` definition
-  override global-level `before_script` definition when concatenated with `script` definition.
-- Executed together with main `script` script as one script in a single shell context.
+- Concatenated with scripts specified in the main `script`. Job-level
+  `before_script` definition override global-level `before_script` definition
+  when concatenated with `script` definition.
+- Executed together with main `script` script as one script in a single shell
+  context.
 
-Script specified in `after_script`:
+Scripts specified in `after_script`:
 
 - Have a current working directory set back to the default.
-- Is executed in a shell context separated from `before_script` and `script` scripts.
-- Because of separated context, cannot see changes done by scripts defined in `before_script` or `script` scripts:
-    - in shell - for example, command aliases and variables exported in `script` script,
-    - outside of the working tree (depending on the Runner executor) - for example, software installed
-      by a `before_script` or `script` script.
+- Are executed in a shell context separated from `before_script` and `script`
+  scripts.
+- Because of separated context, cannot see changes done by scripts defined
+  in `before_script` or `script` scripts, either:
+  - In shell. For example, command aliases and variables exported in `script`
+    scripts.
+  - Outside of the working tree (depending on the Runner executor). For example,
+    software installed by a `before_script` or `script` scripts.
 
 It's possible to overwrite the globally defined `before_script` and `after_script`
 if you set it per-job: