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

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

Author: Feediver1

local-antora-playbook.yml

@@ -15,14 +15,17 @@ content:
   - url: .
     branches: HEAD
   - url: https://github.com/redpanda-data/docs
-    branches: [v/*, api, shared, site-search,'!v-end-of-life/*']
+    branches: [main, v/*, '!v/25.1', api, shared, site-search,'!v-end-of-life/*']
   - url: https://github.com/redpanda-data/cloud-docs
     branches: 'main'
   - url: https://github.com/redpanda-data/redpanda-labs
     branches: main
     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,9 @@ 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.
 
+// DOC-2237: maintenance-then-decommission requirement was only true for 22.x. See node-management.adoc for the matching context note.
+NOTE: Entering xref:manage:node-management.adoc[maintenance mode] before decommissioning is optional. Decommissioning drains partition leadership gracefully on its own.
+
 == 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

@@ -16,6 +16,8 @@ You may want to decommission a broker in the following situations:
 
 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 optional. Decommissioning drains partition leadership gracefully on its own.
+
 == Prerequisites
 
 You must have the following:

modules/manage/pages/node-management.adoc

@@ -6,7 +6,8 @@
 
 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>`.
+// DOC-2237: from 24.1.15 / 24.2.1 onward, decommission gracefully drains leadership, so maintenance mode beforehand is optional. Kept the prior CAUTION block accurate to behavior, not pre-22.x semantics.
+NOTE: Putting a broker into maintenance mode before decommissioning is optional. Decommissioning gracefully drains partition leadership on its own, so you can decommission a broker directly without first entering maintenance mode.
 
 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

@@ -102,10 +102,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