1 files changed, 46 insertions, 64 deletions
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index accf6340398..3b9f9be2f6e 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -674,6 +674,10 @@ as Review Apps. You can see a simple example using Review Apps at
   by default.
 - From GitLab 9.2, caches are restored before [artifacts](#artifacts).
 
+TIP: **Learn more:**
+Read how caching works and find out some good practices in the
+[caching dependencies documentation](../caching/index.md).
+
 `cache` is used to specify a list of files and directories which should be
 cached between jobs. You can only use paths that are within the project
 workspace.
@@ -681,35 +685,20 @@ workspace.
 If `cache` is defined outside the scope of jobs, it means it is set
 globally and all jobs will use that definition.
 
-Cache all files in `binaries` and `.config`:
-
-```yaml
-rspec:
-  script: test
-  cache:
-    paths:
-    - binaries/
-    - .config
-```
-
-Cache all Git untracked files:
+### `cache:paths`
 
-```yaml
-rspec:
-  script: test
-  cache:
-    untracked: true
-```
+Use the `paths` directive to choose which files or directories will be cached.
+Wildcards can be used as well.
 
-Cache all Git untracked files and files in `binaries`:
+Cache all files in `binaries` that end in `.apk` and the `.config` file:
 
 ```yaml
 rspec:
   script: test
   cache:
-    untracked: true
     paths:
-    - binaries/
+    - binaries/*.apk
+    - .config
 ```
 
 Locally defined cache overrides globally defined options. The following `rspec`
@@ -723,33 +712,26 @@ cache:
 rspec:
   script: test
   cache:
-    key: rspec
     paths:
     - binaries/
 ```
 
-Note that since cache is shared between jobs, if you're using different
-paths for different jobs, you should also set a different **cache:key**
-otherwise cache content can be overwritten.
-
-NOTE: **Note:**
-The cache is provided on a best-effort basis, so don't expect that the cache
-will be always present.
-
 ### `cache:key`
 
 > Introduced in GitLab Runner v1.0.0.
 
-The `key` directive allows you to define the affinity of caching
-between jobs, allowing to have a single cache for all jobs,
-cache per-job, cache per-branch or any other way that fits your needs.
+Since the cache is shared between jobs, if you're using different
+paths for different jobs, you should also set a different `cache:key`
+otherwise cache content can be overwritten.
 
-This way, you can fine tune caching, allowing you to cache data between
-different jobs or even different branches.
+The `key` directive allows you to define the affinity of caching between jobs,
+allowing to have a single cache for all jobs, cache per-job, cache per-branch
+or any other way that fits your workflow. This way, you can fine tune caching,
+allowing you to cache data between different jobs or even different branches.
 
 The `cache:key` variable can use any of the
 [predefined variables](../variables/README.md), and the default key, if not set,
-is set as `$CI_JOB_NAME-$CI_COMMIT_REF_NAME` which translates as "per-job and
+is `$CI_JOB_NAME-$CI_COMMIT_REF_NAME` which translates as "per-job and
 per-branch". It is the default across the project, therefore everything is
 shared between pipelines and jobs running on the same branch by default.
 
@@ -757,56 +739,56 @@ NOTE: **Note:**
 The `cache:key` variable cannot contain the `/` character, or the equivalent
 URI-encoded `%2F`; a value made only of dots (`.`, `%2E`) is also forbidden.
 
-**Example configurations**
-
-To enable per-job caching:
-
-```yaml
-cache:
-  key: "$CI_JOB_NAME"
-  untracked: true
-```
-
-To enable per-branch caching:
+For example, to enable per-branch caching:
 
 ```yaml
 cache:
   key: "$CI_COMMIT_REF_SLUG"
-  untracked: true
+  paths:
+  - binaries/
 ```
 
-To enable per-job and per-branch caching:
+If you use **Windows Batch** to run your shell scripts you need to replace
+`$` with `%`:
 
 ```yaml
 cache:
-  key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
-  untracked: true
+  key: "%CI_JOB_STAGE%-%CI_COMMIT_REF_SLUG%"
+  paths:
+  - binaries/
 ```
 
-To enable per-branch and per-stage caching:
+If you use **Windows PowerShell** to run your shell scripts you need to replace
+`$` with `$env:`:
 
 ```yaml
 cache:
-  key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG"
-  untracked: true
+  key: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_SLUG"
+  paths:
+  - binaries/
 ```
 
-If you use **Windows Batch** to run your shell scripts you need to replace
-`$` with `%`:
+### `cache:untracked`
+
+Set `untracked: true` to cache all files that are untracked in your Git
+repository:
 
 ```yaml
-cache:
-  key: "%CI_JOB_STAGE%-%CI_COMMIT_REF_SLUG%"
-  untracked: true
+rspec:
+  script: test
+  cache:
+    untracked: true
 ```
 
-If you use **Windows PowerShell** to run your shell scripts you need to replace
-`$` with `$env:`:
+Cache all Git untracked files and files in `binaries`:
 
 ```yaml
-cache:
-  key: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_SLUG"
-  untracked: true
+rspec:
+  script: test
+  cache:
+    untracked: true
+    paths:
+    - binaries/
 ```
 
 ### `cache:policy`