Merge branch 'docs/grammar-environments' into 'master'

doc/ci/environments.md

@@ -235,7 +235,7 @@ will help us achieve that.
 
 As the name suggests, it is possible to create environments on the fly by just
 declaring their names dynamically in `.gitlab-ci.yml`. Dynamic environments is
-the base of [Review apps](review_apps.md).
+the basis of [Review apps](review_apps.md).
 
 GitLab Runner exposes various [environment variables][variables] when a job runs,
 and as such, you can use them as environment names. Let's add another job in
@@ -344,6 +344,10 @@ review_app:
 It is assumed that the user has already setup NGINX and GitLab Runner in the
 server this job will run on.
 
+>**Note:**
+Be sure to check out the [limitations](#limitations) section for some edge
+cases regarding naming of you branches and Review Apps.
+
 ---
 
 The development workflow would now be:
@@ -489,13 +493,13 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/*
 
 ## Limitations
 
-- You are limited to use only the [CI predefined variables][variables] in the
-  `environment: name`. If you try to re-use variables defined inside `script`
-  as part of the environment name, it will not work.
-- If the branch name contains special characters and you use the
-  `$CI_BUILD_REF_NAME` variable to dynamically create environments, there might
-  be complications during deployment. Follow the [issue 22849][ce-22849] for
-  more information.
+1. If the branch name contains special characters (`/`), and you use the
+   `$CI_BUILD_REF_NAME` variable to dynamically create environments, there might
+   be complications during your Review Apps deployment. Follow the
+   [issue 22849][ce-22849] for more information.
+1. You are limited to use only the [CI predefined variables][variables] in the
+   `environment: name`. If you try to re-use variables defined inside `script`
+   as part of the environment name, it will not work.
 
 ## Further reading
 

doc/ci/review_apps/index.md

@@ -6,7 +6,7 @@
 - Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by
   [Fourchette].
 
-The base of Review Apps is the [dynamic environments] which allow you to create
+The basis of Review Apps is the [dynamic environments] which allow you to create
 a new environment (dynamically) for each one of your branches.
 
 A Review App can then be visible as a link when you visit the [merge request]