DOC-2237: correct decommission + maintenance mode guidance (v/24.1 backport) (#1741)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Feediver1

local-antora-playbook.yml

@@ -23,6 +23,9 @@ content:
     start_paths: [docs,'*/docs']
   - url: https://github.com/redpanda-data/rp-connect-docs
     branches: main
+  - url: https://github.com/redpanda-data/docs-site
+    branches: main
+    start_paths: [home, data-platform, self-managed]
 ui:
   bundle:
     url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zip

modules/manage/pages/cluster-maintenance/decommission-brokers.adoc

@@ -11,6 +11,8 @@ When you decommission a broker, its partition replicas are reallocated across th
 
 CAUTION: When a broker is decommissioned, it cannot rejoin the cluster. If a broker with the same ID tries to rejoin the cluster, it is rejected.
 
+NOTE: Entering xref:manage:node-management.adoc[maintenance mode] before decommissioning is recommended but not required. Maintenance mode reassigns partition leadership up front, which can be smoother for clients than draining leadership during decommissioning.
+
 == What happens when a broker is decommissioned?
 
 When a broker is decommissioned, the controller leader creates a reallocation plan for all partition replicas that are allocated to that broker. By default, this reallocation is done in batches of 50 to avoid overwhelming the remaining brokers with Raft recovery. See xref:reference:tunable-properties.adoc#partition_autobalancing_concurrent_moves[`partition_autobalancing_concurrent_moves`].

modules/manage/pages/kubernetes/k-decommission-brokers.adoc

@@ -14,6 +14,8 @@ When you decommission a broker, its partition replicas are reallocated across th
 
 NOTE: When a broker is decommissioned, it cannot rejoin the cluster. If a broker with the same ID tries to rejoin the cluster, it is rejected.
 
+NOTE: Entering xref:manage:node-management.adoc[maintenance mode] before decommissioning is recommended but not required. Maintenance mode reassigns partition leadership up front, which can be smoother for clients than draining leadership during decommissioning.
+
 == Prerequisites
 
 You must have the following:

modules/manage/pages/node-management.adoc

@@ -6,7 +6,7 @@
 
 Maintenance mode lets you take a Redpanda broker offline temporarily while minimizing disruption to client operations. When a broker is in maintenance mode, you can safely perform operations that require the Redpanda process to be temporarily stopped; for example, system maintenance or a xref:manage:cluster-maintenance/rolling-upgrade.adoc[rolling upgrade].
 
-CAUTION: A broker cannot be decommissioned while it's in maintenance mode. Take the broker out of maintenance mode first by running `rpk cluster maintenance disable <node-id>`.
+NOTE: Putting a broker into maintenance mode before decommissioning is recommended but not required. Maintenance mode reassigns partition leadership up front, which can be smoother for clients than draining leadership during decommissioning.
 
 When a broker is placed in maintenance mode, if the replication factor is greater than one, it reassigns partition leadership to other brokers in the cluster. The broker is not eligible for partition leadership again until it is taken out of maintenance mode.
 

modules/upgrade/partials/rolling-upgrades/enable-maintenance-mode.adoc

@@ -74,10 +74,10 @@ The combination of the `--watch` and `--exit-when-healthy` flags tell rpk to mon
 [NOTE]
 ====
 ifdef::rolling-upgrade[]
-You can also evaluate xref:manage:monitoring.adoc[metrics] to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before proceeding with other operations, such as decommissioning or retrying the rolling upgrade:
+You can also evaluate xref:manage:monitoring.adoc[metrics] to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before retrying the rolling upgrade:
 endif::[]
 ifdef::rolling-restart[]
-You can also evaluate xref:manage:monitoring.adoc[metrics] to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before proceeding with other operations, such as decommissioning or retrying the rolling restart:
+You can also evaluate xref:manage:monitoring.adoc[metrics] to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before retrying the rolling restart:
 endif::[]
 
 ```bash