doc/radosgw: refine "notification reliability"

This commit refines the English in the "Notification Reliability"
section of the notifications.rst page (the "Bucket Notifications"
page). I have also added signposting structure.

Co-authored-by: Anthony D'Atri <anthony.datri@gmail.com>
Co-authored-by: Yuval Lifshitz <ylifshit@redhat.com>
Signed-off-by: Zac Dover <zac.dover@gmail.com>

diff --git a/doc/radosgw/notifications.rst b/doc/radosgw/notifications.rst
index 8d83b717992690c2927af88c3a1391ed18fd0ba4..e4b4e4a7734279cd072917d7c6116052bd266f3c 100644 (file)
--- a/doc/radosgw/notifications.rst
+++ b/doc/radosgw/notifications.rst
@@ -40,18 +40,36 @@ as the S3-compatible API of the `PubSub Module`_.
 Notification Reliability
 ------------------------
 
-Notifications may be sent synchronously, as part of the operation that triggered them.
-In this mode, the operation is acked only after the notification is sent to the topic's configured endpoint, which means that the
-round trip time of the notification is added to the latency of the operation itself.
+Notifications can be sent synchronously or asynchronously. This section
+describes the latency and reliability that you should expect for synchronous
+and asynchronous notifications.
 
-.. note:: The original triggering operation will still be considered as successful even if the notification fail with an error, cannot be delivered or times out
+Synchronous Notifications
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Notifications may also be sent asynchronously. They will be committed into persistent storage and then asynchronously sent to the topic's configured endpoint.
-In this case, the only latency added to the original operation is of committing the notification to persistent storage.
+Notifications can be sent synchronously, as part of the operation that
+triggered them. In this mode, the operation is acknowledged (acked) only after
+the notification is sent to the topic's configured endpoint. This means that
+the round trip time of the notification (the time it takes to send the
+notification to the topic's endpoint plus the time it takes to receive the
+acknowledgement) is added to the latency of the operation itself.
 
-.. note:: If the notification fail with an error, cannot be delivered or times out, it will be retried until successfully acked
+.. note:: The original triggering operation is considered successful even if
+   the notification fails with an error, cannot be delivered, or times out.
 
-.. tip:: To minimize the added latency in case of asynchronous notifications, it is recommended to place the "log" pool on fast media
+Asynchronous Notifications
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Notifications can be sent asynchronously. They are committed into persistent
+storage and then asynchronously sent to the topic's configured endpoint. In
+this case, the only latency added to the original operation is the latency
+added when the notification is committed to persistent storage.
+
+.. note:: If the notification fails with an error, cannot be delivered, or
+   times out, it is retried until it is successfully acknowledged.
+
+.. tip:: To minimize the latency added by asynchronous notification, we 
+   recommended placing the "log" pool on fast media.
 
 
 Topic Management via CLI