diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index a57a046..308e1aa 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -268,7 +268,8 @@
  *
  * Here are the steps to follow to define a new entity type:
  * - Choose a unique machine name, or ID, for your entity type. This normally
- *   starts with your module's machine name.
+ *   starts with (or is the same as) your module's machine name. It should be
+ *   as short as possible, and may not exceed 32 characters.
  * - Define an interface for your entity's get/set methods, extending either
  *   \Drupal\Core\Config\Entity\ConfigEntityInterface or [content entity
  *   interface].