incorporate Simon's feedback

Author: micheleRP

modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc

@@ -93,7 +93,7 @@ Verify that the following conditions exist before proceeding with failover:
 * Topics should be in `ACTIVE` state (not `FAULTED`).
 * Replication lag should be reasonable for your RPO requirements.
 
-**Understanding replication lag**
+==== Understanding replication lag
 
 Use xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] to check lag, which shows the message count difference between source and shadow partitions:
 
@@ -135,7 +135,7 @@ Name: <topic-name>, State: ACTIVE
  1          2345     2579     2568     11
 ----
 
-The partition information shows:
+The partition information shows the following:
 
 * **SRC_LSO**: Source partition last stable offset
 * **SRC_HWM**: Source partition high watermark  

modules/manage/pages/disaster-recovery/shadowing/failover.adoc

@@ -37,13 +37,15 @@ When you initiate failover, Redpanda performs the following operations:
 
 Topic failover is irreversible. Once failed over, topics cannot return to shadow mode, and automatic fallback to the original source cluster is not supported.
 
+NOTE: To avoid a split-brain scenario after failover, ensure that all clients are reconfigured to point to the shadow cluster before resuming write activity. 
+
 == Failover commands
 
 You can perform failover at different levels of granularity to match your disaster recovery needs:
 
 === Individual topic failover
 
-To fail over a specific shadow topic while leaving other topics in the shadow link still replicating:
+To fail over a specific shadow topic while leaving other topics in the shadow link still replicating, run:
 
 [,bash]
 ----
@@ -54,7 +56,7 @@ Use this approach when you need to selectively failover specific workloads or wh
 
 === Complete shadow link failover (cluster failover)
 
-To fail over all shadow topics associated with the shadow link simultaneously:
+To fail over all shadow topics associated with the shadow link simultaneously, run:
 
 [,bash]
 ----
@@ -82,6 +84,7 @@ Force deleting a shadow link is irreversible and immediately fails over all topi
 The shadow link itself has a simple state model:
 
 * **`ACTIVE`**: Shadow link is operating normally, replicating data
+* **`PAUSED`**: Shadow link replication is temporarily halted by user action
 
 Shadow links do not have dedicated failover states. Instead, the link's operational status is determined by the collective state of its shadow topics.
 
@@ -93,10 +96,11 @@ Individual shadow topics progress through specific states during failover:
 * **`FAULTED`**: Shadow topic has encountered an error and is not replicating
 * **`FAILING_OVER`**: Failover initiated, replication stopping
 * **`FAILED_OVER`**: Failover completed successfully, topic fully writable
+* **`PAUSED`**: Replication temporarily halted by user action
 
 == Monitor failover progress
 
-Monitor failover progress using the status command:
+To monitor failover progress using the status command, run:
 
 [,bash]
 ----
@@ -105,7 +109,7 @@ rpk shadow status <shadow-link-name>
 
 The output shows individual topic states and any issues encountered during the failover process. For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`].
 
-**Task states during monitoring:**
+Task states during monitoring:
 
 * **`ACTIVE`**: Task is operating normally and replicating data
 * **`FAULTED`**: Task encountered an error and requires attention
@@ -140,6 +144,8 @@ After successful failover, your shadow cluster exhibits the following characteri
 
 == Failover considerations and limitations
 
+Before implementing failover procedures, understand these key considerations that affect your disaster recovery strategy and operational planning.
+
 **Data consistency:**
 
 * Some data loss may occur due to replication lag at the time of failover.

modules/manage/pages/disaster-recovery/shadowing/monitor.adoc

@@ -42,8 +42,8 @@ rpk shadow status <shadow-link-name>
 
 For troubleshooting specific issues, you can use command options to show individual status sections. See xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] for available status options. The status output includes:
 
-* **Shadow link state**: Overall operational state (`ACTIVE`).
-* **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`).
+* **Shadow link state**: Overall operational state (`ACTIVE`, `PAUSED`).
+* **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`, `PAUSED`).
 * **Task status**: Health of replication tasks across brokers (`ACTIVE`, `FAULTED`, `NOT_RUNNING`, `LINK_UNAVAILABLE`). For details about shadow link tasks, see xref:manage:disaster-recovery/shadowing/setup.adoc#shadow-link-tasks[Shadow link tasks].
 * **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM).
 

modules/manage/pages/disaster-recovery/shadowing/overview.adoc

@@ -34,10 +34,9 @@ Shadowing replicates:
 
 Shadowing addresses enterprise disaster recovery requirements driven by regulatory compliance and business continuity needs. Organizations typically want to minimize both recovery time objective (RTO) and recovery point objective (RPO), and Shadowing asynchronous replication helps you achieve both goals by reducing data loss during regional outages and enabling rapid application recovery.
 
-The architecture follows an active-passive pattern. The source cluster processes all production traffic while the shadow cluster remains in read-only mode, continuously receiving updates. If a disaster occurs, you can failover the shadow topics using the 
-ifndef::env-cloud[Admin API] 
-ifdef::env-cloud[Data Plane API] 
-or `rpk`, making them fully writable. At that point, you can redirect your applications to the shadow cluster, which becomes the new production cluster.
+The architecture follows an active-passive pattern. The source cluster processes all production traffic while the shadow cluster remains in read-only mode, continuously receiving updates. If a disaster occurs, you can failover the shadow topics, making them fully writable. At that point, you can redirect your applications to the shadow cluster, which becomes the new production cluster.
+
+NOTE: To avoid a split-brain scenario after failover, ensure that all clients are reconfigured to point to the shadow cluster before resuming write activity. 
 
 
 ifdef::env-cloud[]
@@ -138,40 +137,30 @@ Partition count is always replicated to ensure the shadow topic matches the sour
 
 The <<shadow-link-tasks,Source Topic Sync task>> handles topic property replication. For topic properties, Redpanda follows these replication rules:
 
-[cols="1,1,1"]
-
-|===
-|Never replicated |Always replicated |Always replicated +
-(unless `exclude_default` is `true`)
-
-|`redpanda.remote.readreplica`
-|`max.message.bytes`
-|`compression.type`
-
-|`redpanda.remote.recovery`
-|`cleanup.policy`
-|`retention.bytes`
+**Never replicated**
 
-|`redpanda.remote.allowgaps`
-|`message.timestamp.type`
-|`retention.ms`
+* `redpanda.remote.readreplica`
+* `redpanda.remote.recovery`
+* `redpanda.remote.allowgaps`
+* `redpanda.virtual.cluster.id`
+* `redpanda.leaders.preference`
+* `redpanda.cloud_topic.enabled`
 
-|`redpanda.virtual.cluster.id`
-|
-|`delete.retention.ms`
+**Always replicated**
 
-|`redpanda.leaders.preference`
-|
-|`replication.factor`
+* `max.message.bytes`
+* `cleanup.policy`
+* `message.timestamp.type`
 
-|`redpanda.cloud_topic.enabled`
-|
-|`min.compaction.lag.ms`
+**Always replicated (unless `exclude_default` is `true`)**
 
-|
-|
-|`max.compaction.lag.ms`
-|===
+* `compression.type`
+* `retention.bytes`
+* `retention.ms`
+* `delete.retention.ms`
+* `replication.factor`
+* `min.compaction.lag.ms`
+* `max.compaction.lag.ms`
 
 To replicate additional topic properties, explicitly list them in `synced_shadow_topic_properties`.