Add latest changes from gitlab-org/gitlab@master

1 files changed, 28 insertions, 30 deletions

diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md
index 0778d598d32..3c9a796a9f2 100644
--- a/doc/ci/caching/index.md
+++ b/doc/ci/caching/index.md
@@ -19,62 +19,60 @@ Use cache for dependencies, like packages you download from the internet.
 Cache is stored where GitLab Runner is installed and uploaded to S3 if
 [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching).
 
-- You can define it per job by using the `cache:` keyword. Otherwise it is disabled.
-- You can define it per job so that:
-  - Subsequent pipelines can use it.
-  - Subsequent jobs in the same pipeline can use it, if the dependencies are identical.
-- You cannot share it between projects.
-
 Use artifacts to pass intermediate build results between stages.
 Artifacts are generated by a job, stored in GitLab, and can be downloaded.
 
-- You can define artifacts per job. Subsequent jobs in later stages of the same
-  pipeline can use them.
-- You can't use the artifacts in a different pipeline.
+Both artifacts and caches define their paths relative to the project directory, and
+can't link to files outside it.
+
+### Cache
+
+- Define cache per job by using the `cache:` keyword. Otherwise it is disabled.
+- Subsequent pipelines can use the cache.
+- Subsequent jobs in the same pipeline can use the cache, if the dependencies are identical.
+- Different projects cannot share the cache.
+
+### Artifacts
+
+- Define artifacts per job.
+- Subsequent jobs in later stages of the same pipeline can use artifacts.
+- Different projects cannot share artifacts.
 
 Artifacts expire after 30 days unless you define an [expiration time](../yaml/README.md#artifactsexpire_in).
 Use [dependencies](../yaml/README.md#dependencies) to control which jobs fetch the artifacts.
 
-Both artifacts and caches define their paths relative to the project directory, and
-can't link to files outside it.
-
 ## Good caching practices
 
-To ensure maximum availability of the cache, when you declare `cache` in your jobs,
-use one or more of the following:
+To ensure maximum availability of the cache, do one or more of the following:
 
 - [Tag your runners](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs
-  that share their cache.
+  that share the cache.
 - [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects).
-- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example,
-  different caches on each branch). For that, you can take advantage of the
-  [predefined CI/CD variables](../variables/README.md#predefined-cicd-variables).
+- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow. For example,
+  you can configure a different cache for each branch.
 
 For runners to work with caches efficiently, you must do one of the following:
 
 - Use a single runner for all your jobs.
-- Use multiple runners (in autoscale mode or not) that use
+- Use multiple runners that have
   [distributed caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching),
-  where the cache is stored in S3 buckets (like shared runners on GitLab.com).
-- Use multiple runners (not in autoscale mode) of the same architecture that
-  share a common network-mounted directory (using NFS or something similar)
-  where the cache is stored.
-
-Read about the [availability of the cache](#availability-of-the-cache)
-to learn more about the internals and get a better idea how cache works.
+  where the cache is stored in S3 buckets. Shared runners on GitLab.com behave this way. These runners can be in autoscale mode,
+  but they don't have to be. 
+- Use multiple runners with the same architecture and have these runners
+  share a common network-mounted directory to store the cache. This directory should use NFS or something similar.
+  These runners must be in autoscale mode. 
 
 ### Share caches between jobs in the same branch
 
-Define a cache with the `key: ${CI_COMMIT_REF_SLUG}` so that jobs of each
-branch always use the same cache:
+To have jobs for each branch use the same cache, define a cache with the `key: ${CI_COMMIT_REF_SLUG}`:
 
 ```yaml
 cache:
   key: ${CI_COMMIT_REF_SLUG}
 ```
 
-This configuration is safe from accidentally overwriting the cache, but merge requests
-get slow first pipelines. The next time a new commit is pushed to the branch, the
+This configuration prevents you from accidentally overwriting the cache. However, the
+first pipeline for a merge request is slow. The next time a commit is pushed to the branch, the
 cache is re-used and jobs run faster.
 
 To enable per-job and per-branch caching: