examples/annotations: update README

Author: mschristensen

examples/pub-sub-message-annotations/javascript/README.md

@@ -1,31 +1,39 @@
-# Using message annotations with Pub/Sub
+# Adding annotations to messages with Pub/Sub
 
-This example demonstrates how to use Ably's message annotations feature to add additional metadata to messages in a pub/sub system. Message annotations allow clients to add reactions, flags, or other metadata to messages without modifying the original message content.
+Enable users to annotate messages with additional data, such as reactions, flags, or other contextual information without modifying the original message content.
+
+Message annotations provide a powerful way to extend messages with additional information. Unlike editing a message, annotations allow multiple clients to add their own metadata while preserving the original message. This is ideal for implementing features like reactions, content categorization, moderation flags, or any other metadata that enhances message context.
+
+Message annotations are implemented using [Ably Pub/Sub](/docs/channels). The Pub/Sub SDK with annotations provides a way to add structured metadata to messages, with support for different annotation types and automatic summarization.
 
 ## Resources
 
-- [Ably Documentation](https://ably.com/docs)
-- [Message Annotations Documentation](https://ably.com/docs/messages/annotations)
+Use the following methods to work with message annotations in a pub/sub application:
 
-The channel name must be in a mutable message namespace, which is why we're using `mutable:pub-sub-message-annotations` in this example.
+- [`channels.get()`](/docs/channels#create) - creates a new or retrieves an existing `channel`. Specify the `ANNOTATION_PUBLISH` and `ANNOTATION_SUBSCRIBE` modes to publish and subscribe to message annotations.
+- [`channel.subscribe()`](/docs/pub-sub#subscribe) - subscribes to message events within a specific channel by registering a listener. Message events with a `message.create` action are received when a user publishes a message. Message events with a `message.summary` action are received when a user publishes or deletes an annotation.
+<!-- TODO links -->
+- `channel.annotations.publish()` - publishes an annotation for a specific message
+- `channel.annotations.subscribe()` - subscribes to receive individual annotation events
+- `channel.annotations.delete()` - deletes a previously published annotation
 
-## Features
+<!-- TODO link -->
+Find out more about annotations.
 
-In this example, you can:
+## Annotation Types
 
-1. Publish messages to a channel
-2. Add annotations to messages using different annotation types:
-   - **distinct.v1**: Track different values with client IDs that created them
-   - **unique.v1**: Similar to distinct, but only the first client ID is recorded
-   - **multiple.v1**: Track counts of values by different clients
-   - **flag.v1**: Simple flags with client IDs
-   - **total.v1**: Count the total annotations
+This example demonstrates five common annotation types, each suited to different use cases:
 
-3. View annotation summaries showing:
-   - How many of each annotation type exist
-   - Which clients contributed annotations
-   - The values of annotations
-   - Expandable/collapsible sections for detailed information
+<!-- TODO -->
+
+## Features
+
+This example demonstrates:
+
+1. Publishing regular messages to a channel
+2. Adding different types of annotations to messages
+3. Viewing both summarized and raw annotation data
+4. Deleting annotations
 
 ## Getting started
 
@@ -63,16 +71,19 @@ In this example, you can:
 
 7. Try it out by opening two tabs to [http://localhost:5173/](http://localhost:5173/) with your browser to see the result.
 
+## Technical notes
+
+- Annotations require a channel in the mutable channel namespace. This example uses `mutable:pub-sub-message-annotations`
+- Annotations are logically grouped by an annotation namespace. This example uses `my-annotations`
+
 ## How to use this example
 
-1. Enter a message in the input field and click "Publish" to send it to the channel.
-2. After publishing a message, you'll see it appear in the message list with an expandable annotation interface.
-3. To add an annotation, select an annotation type from the dropdown menu, enter a value, and click "Publish".
-4. Open the example in multiple browser tabs with different URL parameters (e.g., `?clientId=user1` and `?clientId=user2`) to see how annotations from different clients are handled.
-5. Experiment with different annotation types:
-   - For reactions, try using the "multiple.v1" type with values like "👍" or "❤️"
-   - For flagging content, use the "flag.v1" type
-   - For tracking unique entries, use "distinct.v1" or "unique.v1"
+1. Enter a message in the input field and click "Publish" to send it to the channel
+2. Click on a message to expand it and reveal the annotation interface
+3. Select an annotation type, enter a value, and click "Publish" to add an annotation
+4. Switch between the "Summary" and "Raw Annotations" tabs to see different views
+5. Open the example in multiple browser tabs with different client IDs (e.g., `?clientId=user1` and `?clientId=user2`) to see how annotations from different clients are handled and summarized
+6. Delete annotations by clicking the trash icon in the raw annotations view and see how the summary is updated
 
 ## Open in CodeSandbox