core/modules/system/core.api.php | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 407e439..61d87b0 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -372,9 +372,25 @@
  * compute. Caching can be permanent, temporary, or valid for a certain
  * timespan, and the cache can contain any type of data.
  *
+ * The most important thing to know and remember while caching things is the
+ * trifecta of cache metadata:
+ * 1. cache keys: an array of keys that together identify the thing you are
+ *    caching. That could also be a specific configuration of the thing, such as
+ *    a specific view mode (configuration) of an entity (thing).
+ * 2. cache contexts: an array of contexts that indicate the context in which
+ *    the representation of the thing (see 1.) is being viewed. Simply put: the
+ *    state of the viewer (which user, which language, which country …) that
+ *    requires a specific variation of the thing.
+ * 3. cache tags: an array of tags that describe the thing being cached and
+ *    that indicate the dependencies used in this specific variation. In one
+ *    view mode, a certain entity field may be visible (and hence the cache tags
+ *    for that field must be present), but in another, it may be invisible (and
+ *    hence those cache tags must be absent).
+ *
  * To use the Cache API:
  * - Request a cache object through \Drupal::cache() or by injecting a cache
  *   service.
+ * - Define cache keys
  * - Define a Cache ID (cid) value for your data. A cid is a string, which must
  *   contain enough information to uniquely identify the data. For example, if
  *   your data contains translated strings, then your cid value must include the