Annotations: further tweaks

Author: SimonWoolf

src/pages/docs/messages/annotations.mdx

@@ -21,7 +21,7 @@ When clients publish or delete an annotation, Ably automatically creates a [summ
 Annotations can be enabled for a channel or channel namespace with the *Message annotations, updates, and deletes* channel rule.
 
 <Aside data-type='important'>
-Note that when message annotations are enabled, messages are [persisted](/docs/storage-history/storage#all-message-persistence) by default, and [continuous history](/docs/storage-history/history#continuous-history) features are not currently supported.
+Note that when message annotations are enabled, messages are [persisted](/docs/storage-history/storage#all-message-persistence) (whether or not persistence is enabled) in order to support the feature, which may increase your package quota usage. [Continuous history](/docs/storage-history/history#continuous-history) features are not yet supported (if you are currently using continuous history, be aware that for the moment, enabling annotations, updates, and deletes will break that feature!).
 </Aside>
 
 1. Go to the [**Settings**](https://ably.com/accounts/any/apps/any/edit) tab of an app in your dashboard.
@@ -166,9 +166,9 @@ Deleting an annotation removes all contributions made by that `clientId` for tha
 
 ## Publish annotations <a id="publish" />
 
-To publish an annotation for a message, use the `annotations.publish()` method on a channel. Pass in either a [message](/docs/messages) instance or the `serial` of the message to annotate. This method will publish an annotation message with an action of `annotation.create`.
+To publish an annotation for a message, use the `annotations.publish()` method on a channel. Pass in either a [message](/docs/messages) instance or the `serial` of the message to annotate. This method will publish an annotation with the action `annotation.create`.
 
-The `clientId` specified in the [client options](/docs/api/realtime-sdk#client-options) will be associated with the published annotation. Note that certain annotation types require the client to be identified with a `clientId` in order to publish annotations.
+Certain annotation summarization methods require a client to be [identified](/docs/auth/identified-clients) for them to be able to publish an annotation. Their `clientId` will then be included in the associated published annotation.
 
 Specify the [annotation type](#annotation-types) using the `type` field of the annotation object.
 
@@ -292,7 +292,7 @@ The recommended way to receive annotation updates is through annotation summarie
 
 Annotation summaries are delivered to subscribers as messages with an `action` of `message.summary`, and a `serial` matching the `serial` of the message that they are updating. They have an `annotations` field which contains a `summary` of all the annotations for the message.
 
-The value of the `summary` field is an object where the keys are the [annotation types](#annotation-types). The structure of the value of each key depends on the summarization method used, for example `total.v1` will have a `total` field, while `flag.v1` will have `total` and `clientIds` fields.
+The value of that `summary` field is an object where the keys are the [annotation types](#annotation-types). The structure of the value of each key depends on the summarization method used, for example `total.v1` will have a `total` field, while `flag.v1` will have `total` and `clientIds` fields.
 
 <Aside data-type='note'>
 Subscribing to annotations uses the same method as [subscribing to regular messages](/docs/pub-sub#subscribe) on a channel. When using message annotations, regular messages delivered to the `subscribe()` listener will have an `action` of `message.create`.
@@ -396,9 +396,9 @@ The summary will be included in the message's `summary` field, which is an objec
 
 It is also possible to subscribe to individual annotation events, rather than annotation summaries. These are the emitted when [publishing](#publish) or [deleting](#delete) an annotation.
 
-Individual events can be useful for activity feeds or detailed logging, however annotation summaries are generally more reliable and efficient for maintaining UI state.
+Individual events can be useful for activity feeds or detailed logging, but generally, for most usecases, subscribed clients should relying on aggregated summaries. The aggregation of annotations for a message into a summary attached to the message is the primary benefit of using the annotations API; an app design oriented around every client needing to subscribe to raw annotation events may not be taking full advantage of the feature.
 
-Subscribe to individual annotation events using the `annotations.subscribe()` method on a channel. To subscribe to individual annotations, you must request the `ANNOTATION_SUBSCRIBE` [mode](/docs/channels/options#modes).
+But if you need to, you can subscribe to individual annotation events using the `annotations.subscribe()` method on a channel. To subscribe to individual annotations, you must request the `ANNOTATION_SUBSCRIBE` [mode](/docs/channels/options#modes).
 
 <Aside data-type='note'>
 When you provide an explicit `modes` property for a channel, you override the set of [default modes](/docs/channels/options#modes). It is likely that you will be using features other than just annotations on the channel, so ensure that you also include the other `modes` that you require.