diff --git a/docs/reference/upgrade/cluster_restart.asciidoc b/docs/reference/upgrade/cluster_restart.asciidoc
index 7989f14eaada3..39b6356e9353d 100644
--- a/docs/reference/upgrade/cluster_restart.asciidoc
+++ b/docs/reference/upgrade/cluster_restart.asciidoc
@@ -94,13 +94,19 @@ reenable allocation.
 ------------------------------------------------------
 PUT _cluster/settings
 {
-  "persistent": {
+  "transient": {
     "cluster.routing.allocation.enable": "all"
   }
 }
 ------------------------------------------------------
 // CONSOLE
 
+NOTE: Because <<cluster-update-settings.html#_precedence_of_settings, transient
+settings take precedence over persistent settings>>, this overrides the
+persistent setting used to disable shard allocation in the first step. If you
+don't explicitly reenable shard allocation after a full cluster restart, the
+persistent setting is used and shard allocation remains disabled.
+
 Once allocation is reenabled, the cluster starts allocating replica shards to
 the data nodes. At this point it is safe to resume indexing and searching,
 but your cluster will recover more quickly if you can wait until all primary
diff --git a/docs/reference/upgrade/rolling_upgrade.asciidoc b/docs/reference/upgrade/rolling_upgrade.asciidoc
index f52f354b80b5c..6904430f1c5c0 100644
--- a/docs/reference/upgrade/rolling_upgrade.asciidoc
+++ b/docs/reference/upgrade/rolling_upgrade.asciidoc
@@ -69,6 +69,12 @@ GET _cat/nodes
 +
 --
 
+NOTE: Because <<cluster-update-settings.html#_precedence_of_settings, transient
+settings take precedence over persistent settings>>, this overrides the
+persistent setting used to disable shard allocation in the first step. If you
+don't explicitly reenable shard allocation after a full cluster restart, the
+persistent setting is used and shard allocation remains disabled.
+
 Once the node has joined the cluster, reenable shard allocation to start using
 the node:
 
@@ -156,4 +162,4 @@ In the unlikely case of a network malfunction during the upgrade process that
 isolates all remaining old nodes from the cluster, you must take the
 old nodes offline and upgrade them to enable them to join the cluster.
 
-====================================================
\ No newline at end of file
+====================================================