Reorg document for better reading flow46806-typed-ci-variables-docs

1 files changed, 33 insertions, 27 deletions

diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index bd31d1e2b69..ace439900ab 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -52,6 +52,33 @@ or directly in the `.gitlab-ci.yml` file and reuse them as you wish.
 That can be very powerful as it can be used for scripting without
 the need to specify the value itself.
 
+#### Variable types
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46806) in GitLab 11.11.
+
+There are two types of variables supported by GitLab:
+
+- `env_var`: the runner will create environment variable named same as the variable key and set its value to the variable value.
+- `file`: the runner will write the variable value to a temporary file and set the path to this file as the value of an environment variable named same as the variable key.
+
+#### Masked variables
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/13784) in GitLab 11.10
+
+By default, variables will be created as masked variables.
+This means that the value of the variable will be hidden in job logs,
+though it must match certain requirements to do so:
+
+- The value must be in a single line.
+- The value must not have escape characters.
+- The value must not use variables.
+- The value must not have any whitespace.
+- The value must be at least 8 characters long.
+
+If the value does not meet the requirements above, then the CI variable will fail to save.
+In order to save, either alter the value to meet the masking requirements
+or disable **Masked** for the variable.
+
 ## Getting started
 
 To get started with environment variables in the scope of GitLab
@@ -104,7 +131,10 @@ let's say you want to output `HELLO WORLD` for a `TEST` variable.
 You can either set the variable directly in the `.gitlab-ci.yml`
 file or through the UI.
 
-#### Via [`.gitlab-ci.yml`](../yaml/README.md#variables)
+#### Via `.gitlab-ci.yml`
+
+To create a new custom `env_var` variable via [`.gitlab-ci.yml`](../yaml/README.md#variables), define their variable/value pair under
+`variables`:
 
 ```yaml
 variables:
@@ -117,18 +147,12 @@ For a deeper look into them, see [`.gitlab-ci.yml` defined variables](#gitlab-ci
 
 From the UI, navigate to your project's **Settings > CI/CD** and
 expand **Variables**. Create a new variable by choosing its **type**, naming
-it in the field **Input variable key**, and define its value in the
+it in the field **Input variable key**, and defining its value in the
 **Input variable value** field:
 
 ![CI/CD settings - new variable](img/new_custom_variables_example.png)
 
-##### Variable Types
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46806) in GitLab 11.11.
-
-Supported variable types are:
-* `env_var` - The runner will create environment variable named same as the variable key and set its value to the variable value.
-* `file` - The runner will write the variable value to a temporary file and set the path to this file as the value of an environment variable named same as the variable key.
+You'll also see the option to mask and/or protect your variables.
 
 Once you've set the variables, call them from the `.gitlab-ci.yml` file:
 
@@ -146,24 +170,6 @@ The output will be:
 
 ![Output custom variable](img/custom_variables_output.png)
 
-### Masked Variables
-
-By default, variables will be created as masked variables.
-This means that the value of the variable will be hidden in job logs,
-though it must match certain requirements to do so:
-
-- The value must be in a single line.
-- The value must contain only letters, numbers, or underscores.
-- The value must not have escape characters, such as `\"`
-- The value must not use variables.
-- The value must not have any whitespace.
-- The value must be at least 8 characters long.
-
-The above rules are validated using the regex `/\A\w{8,}\z/`. If the value
-does not meet the requirements above, then the CI variable will fail to save.
-In order to save, either alter the value to meet the masking requirements or
-disable `Masked` for the variable.
-
 ### Syntax of environment variables in job scripts
 
 All variables are set as environment variables in the build environment, and