Update message / annotations docs for protocol v4 messages

And remove references to `version` for now until we add the
update/delete docs.

Our docs will just unconditionally use protocol v4 message docs for
annotations and updates, since by the time we release those features
experimentally all 3 sdks which had support for them will be updated to
v4.

Author: SimonWoolf

content/api/realtime-sdk/messages.textile

@@ -25,3 +25,8 @@ h2(#properties).
   python:  Attributes
 
 <%= partial partial_version('types/_message') %>
+
+h2(#message-annotations).
+  default: MessageAnnotations
+
+<%= partial partial_version('types/_message_annotations') %>

content/api/realtime-sdk/types.textile

@@ -87,10 +87,10 @@ blang[jsall].
 
   <%= partial partial_version('types/_message_action') %>
 
-  h3(#message-operation).
-    default: Operation
+h3(#message-annotations).
+  default: MessageAnnotations
 
-  <%= partial partial_version('types/_operation') %>
+<%= partial partial_version('types/_message_annotations') %>
 
 h3(#presence-message).
   default: PresenceMessage

content/partials/types/_message.textile

@@ -51,7 +51,7 @@ h6(#timestamp).
   default: timestamp
   csharp: Timestamp
 
-Timestamp when the message was received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span>__
+Timestamp when the message was first received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span>__
 
 h6(#encoding).
   default: encoding
@@ -69,22 +69,12 @@ blang[jsall].
   h6(#serial).
     default: serial
 
-  This message's unique serial (an identifier that will be the same in all future updates of this message).<br>__Type: @String@__
+  The message's serial (a server-assigned identifier that will be the same in all future updates of this message, and can be used to add annotations). Right now this will only be set if you enable annotations in "channel rules":/docs/channels#rules .<br>__Type: @String@__
 
-  h6(#created-at).
-    default: createdAt
+  h6(#annotations).
+    default: annotations
 
-  The timestamp of the very first version of a given message (will differ from @timestamp@ only if the message has been updated or deleted).<br>__Type: @Integer@__
-
-  h6(#version).
-    default: version
-
-  The version of the message, lexicographically-comparable with other versions (that share the same serial). Will differ from the serial only if the message has been updated or deleted.<br>__Type: @String@__
-
-  h6(#operation).
-    default: operation
-
-  In the case of an updated or deleted message, this will contain metadata about the update or delete operation.<br>__Type: "@Operation@":/docs/api/realtime-sdk/types#message-operation__
+  An object containing information about annotations that have been made to the object.<br>__Type: "@MessageAnnotations@":/docs/api/realtime-sdk/types#message-annotations__
 
 h3(constructors).
   default: Message constructors

content/partials/types/_message_annotations.textile

@@ -0,0 +1,7 @@
+h4.
+  default: Properties
+  java:    Members
+  ruby:    Attributes
+  python:  Attributes
+
+- <span lang="default">summary</span> := An object whose keys are annotation types, and the values are aggregated summaries for that annotation type<br>__Type: @Record<String, JsonObject>@__

content/partials/types/_operation.textile

@@ -24,8 +24,7 @@ Annotations can be enabled for a channel or channel namespace with the *Message
 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.
 </Aside>
 
-1. On your [dashboard](https://ably.com/accounts/any), select one of your apps.
-2. Go to **Settings**.
+1. Go to the [**Settings**](https://ably.com/accounts/any/apps/any/edit) tab of an app in your dashboard.
 3. Under [channel rules](/docs/channels#rules), click **Add new rule**.
 4. Enter the channel name or channel namespace on which to enable message annotations.
 5. Check **Message annotations, updates, and deletes** to enable message annotations.
@@ -189,7 +188,7 @@ await channel.annotations.publish(message, {
   name: 'delivered'
 });
 
-// You can also use a message's serial number
+// You can also use a message's `serial`
 await channel.annotations.publish(message.serial, {
   type: 'receipts:flag.v1',
   name: 'delivered'
@@ -211,7 +210,7 @@ await channel.annotations.publish(message, {
   name: 'delivered'
 });
 
-// You can also use a message's serial number
+// You can also use a message's `serial`
 await channel.annotations.publish(message.serial, {
   type: 'receipts:flag.v1',
   name: 'delivered'
@@ -283,11 +282,11 @@ await channel.annotations.delete(message.serial, {
 ```
 </Code>
 
-## Subscribe to annotations <a id="subscribe" />
+## Subscribe to annotation summaries <a id="subscribe" />
 
 The recommended way to receive annotation updates is through annotation summaries. These events provide a summary of the complete, current state of all annotations for a message whenever an annotation is published or deleted.
 
-Annotation summaries are delivered to subscribers as messages with an `action` of `message.summary`. These messages have a `summary` field which provides a summary of all the annotations for the message, identified by the `serial` field on the summary message.
+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.
 

src/pages/docs/messages/annotations.mdx

@@ -27,16 +27,15 @@ The following are the properties of a message:
 |----------|-------------|
 | **name** | The name of the message |
 | **data** | The contents of the message. Also known as the message payload |
-| **id** | Each message sent through Ably is assigned a unique ID, unless you provide your own ID. Client specified IDs ensure [publishes are idempotent](/docs/pub-sub/advanced#idempotency) |
+| **id** | Each message sent through Ably is assigned a unique ID, unless you provide your own ID, which serves as the [idempotency key](/docs/pub-sub/advanced#idempotency) |
 | **clientId** | The [ID of the client](/docs/auth/identified-clients) that published the message |
 | **connectionId** | The ID of the connection used to publish the message |
-| **timestamp** | The timestamp of when the message was received by Ably, as milliseconds since the Unix epoch |
+| **timestamp** | The timestamp of when the message was first received by Ably, as milliseconds since the Unix epoch |
 | **extras** | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include those related to [Push Notifications](/docs/push), [deltas](/docs/channels/options/deltas) and headers |
 | **encoding** | This is typically empty, as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute contains the remaining transformations not applied to the data payload |
-
-<aside data-type='note'>
-Additional properties are included on a message when using message [annotations](/docs/messages/annotations) .
-</aside>
+| **action** | An [enum](/docs/api/realtime-sdk/types#message-action) telling you whether this is a normal ('create') message, an update to a previous message, an annotation summary, etc. |
+| **serial** | The message's serial (a server-assigned identifier that will be the same in all future updates of this message, and can be used to add [annotations](/docs/messages/annotations)). Right now this will only be set if you enable annotations in [channel rules](/docs/channels#rules) |
+| **annotations** | An object containing a summary of any [annotations](/docs/messages/annotations) that have been made to the message |
 
 ## Message conflation <a id="conflation"/>