Fix syntax description in rpk cluster partitions transfer-leadership (#1125)

Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>

Author: kbatuigas

modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-transfer-leadership.adoc

@@ -1,10 +1,11 @@
 = rpk cluster partitions transfer-leadership
 
-Transfer partition leadership between brokers.
+Transfer partition leadership between brokers. This command supports transferring only one partition leader at a time.
 
-You can transfer only one partition leader at a time.
-
-WARNING: Redpanda tries to balance leadership distribution across brokers by default. If the distribution of leaders becomes uneven as a result of transferring leadership across brokers, the cluster may move leadership back to the original brokers automatically.
+NOTE: Redpanda tries to balance leadership distribution across brokers by default.
+If the distribution of leaders becomes uneven as a result of transferring leadership
+across brokers, the cluster may move leadership back to the original
+brokers automatically.
 
 == Usage
 
@@ -15,20 +16,22 @@ rpk cluster partitions transfer-leadership [flags]
 
 == Examples
 
-Transfer partition leadership:
+To transfer partition leadership for a partition `0` to a broker ID `2`, run:
 
 ```bash
 rpk cluster partitions transfer-leadership foo --partition 0:2
 ```
 
-The preceding example shows how to transfer leadership for the partition `kafka/foo/0` to broker 2. By default, it uses the `kafka` namespace, but you can specify an internal namespace using the `+{namespace}/+` prefix.
-
-Equivalent command using different syntax:
+The `--partition` flag accepts a value `<A>:<B>`, where `A` is a topic-partition and `B` is the ID of the broker to which you want to transfer leadership. To specify a topic-partition, you can use just the partition ID (`0`) or also use the topic name together with the partition using the following syntax:
 
 ```bash
-rpk cluster partitions transfer-leadership --partition foo/0:2
+rpk cluster partitions transfer-leadership --partition test-topic/0:2
 ```
 
+In this case, the name of the topic is `test-topic` and the partition ID is `0`.
+
+The preceding examples transfer leadership for the partition `kafka/test-topic/0`. The command behavior is based on the assumption that the default namespace is `kafka`, but you can also specify an internal namespace using the `+{namespace}/+` prefix.
+
 == Flags
 
 [cols="1m,1a,2a"]
@@ -39,7 +42,7 @@ rpk cluster partitions transfer-leadership --partition foo/0:2
 
 |-h, --help |- |Help for transfer-leadership.
 
-|-p, --partition |string |The topic partition to which to transfer leadership and specify the new leader location. Syntax `-p A:B` where A is the partition leader and B will be the new leader. See <<examples>> for how to use it. 
+|-p, --partition |string |Specify the topic-partition's leadership to transfer and the location of the new leader. Use the syntax `-p <topic-partition>:<new-leader-broker-ID>`. 
 
 |--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`.