diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 3dbf1afc7a96ca8e7b2730be1e3e98f8620d5f92..7e2edb945da6035e586d7fbd7cf3e8c0cb2c07c5 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -113,6 +113,9 @@ The YAML-defined variables are also set to all created service containers, thus
 
 ### cache
 `cache` is used to specify list of files and directories which should be cached between builds.
+Caches are stored according to the branch/ref and the job name. Caches are not
+currently shared between different job names or between branches/refs. This means
+caching will benefit you if you push subsequent commits to an existing feature branch.
 
 **The global setting allows to specify default cached files for all jobs.**