diff --git a/core/modules/system/system.api.php b/core/modules/system/system.api.php
index 3334d48..8083f89 100644
--- a/core/modules/system/system.api.php
+++ b/core/modules/system/system.api.php
@@ -415,8 +415,19 @@ function hook_page_build(&$page) {
  *
  * @return array
  *   An array of default menu links. Each link has a key that is the machine
- *   name, which must be unique. The corresponding array value is an
- *   associative array that may contain the following key-value pairs:
+ *   name, which must be unique. By default, use the route name as the
+ *   machine name. In cases where multiple links use the same route name, such
+ *   as two links to the same page in different menus, or two links using the
+ *   same route name but different route parameters, the suggested machine name
+ *   patten is the route name followed by a dot and a unique suffix. For
+ *   example, an additional logout link might have a machine name of
+ *   user.logout.navigation, and default links provided to edit the article and
+ *   page content types could use machine names node.type_edit.article and
+ *   node.type_edit.page. Since the machine name may be arbitrary, you should
+ *   never write code that assumes it is identical to the route name.
+ *
+ *   The value corresponding to each machine name key is an associative array
+ *   that may contain the following key-value pairs:
  *   - link_title: (required) The untranslated title of the menu item.
  *   - description: The untranslated description of the link.
  *   - route_name: (optional) The route name to be used to build the path.
diff --git a/core/modules/system/tests/modules/menu_test/menu_test.module b/core/modules/system/tests/modules/menu_test/menu_test.module
index 0487863..4d31718 100644
--- a/core/modules/system/tests/modules/menu_test/menu_test.module
+++ b/core/modules/system/tests/modules/menu_test/menu_test.module
@@ -11,7 +11,7 @@
  * Implements hook_menu_link_defaults().
  *
  * Many of the machine names here are slightly different from the route name.
- * Since the machine name is arbitrary, this helps insure that core does not
+ * Since the machine name is arbitrary, this helps ensure that core does not
  * add mistaken assumptions about the correlation.
  */
 function menu_test_menu_link_defaults() {