Adds USPs to chat docs #3056

franrob-projects · 2025-12-23T16:02:33Z

This PR:

Adds temporary USP components.
Adds short statements within USP components that direct the user to supporting evidence in Ably's architecture docs.

Note that once the copy has been confirmed, I will then add the finished components designed by Lenker.

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

coderabbitai · 2025-12-23T16:02:39Z

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

* Add relevant platform guarantee asides to chat documentation pages * Standardize aside format to use "See evidence here 🕵️" consistently * Fix Admonition component fallback for undefined dataType * Resolve merge conflict in Aside component Pages updated: - Chat index: Added scaling guarantee - Chat setup: Added connection recovery guarantee - Chat connect: Added edge network failure resolution - Chat integrations: Added throughput capability evidence - Messages: Added message ordering guarantee with improved context - Typing indicators: Added latency guarantee for real-time feedback - Presence: Added connection recovery for online status reliability - Room reactions: Added latency guarantee for ephemeral reactions - Replies: Added state integrity guarantee for reply chains - Media sharing: Added fault tolerance for media references - Message reactions: Added state integrity for reaction persistence - React UI Kit index: Updated format consistency - History: Updated format consistency - Rooms index: Updated format consistency 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

GregHolmes

Thanks Fran, I've gone through each addition and feel there may need some changes to be made to further improve these.

GregHolmes · 2026-01-19T13:11:59Z

src/pages/docs/chat/react-ui-kit/index.mdx

-
 ![Ably Chat React App](../../../../images/examples/chat-ui-app.png)

+<Aside data-type='see-evidence'>


I don't understand the relevance for the Aside in this page. Plus the space between the image and the Aside doesn't exist.

GregHolmes · 2026-01-19T13:12:35Z

src/pages/docs/chat/rooms/history.mdx


 The history feature enables users to retrieve messages that have been previously sent in a room. Ably stores chat messages for 30 days by default. You can extend this up to 365 days by [contacting us](https://ably.com/support).
-
-## Retrieve previously sent messages <a id="history"/>


Why have we removed the header here?

GregHolmes · 2026-01-19T13:13:40Z

src/pages/docs/chat/rooms/history.mdx

 | limit | Maximum number of messages to be retrieved per page, up to 1,000. |

+<Aside data-type='see-evidence'>
+Ably maintains message continuity for up to 2 minutes during disconnections. The SDKs automatically handle reconnection and deliver all missed messages. [See evidence here 🕵️](/docs/platform/architecture/connection-recovery)


This is not relevant to chat. Messages in Chat are stored for 30 days by default, which can be extended for up to 365 days.

That said this Aside is just repeated what's stated in the first 3 sentences (first paragraph) of the page. I'd recommend removing it from this page.

GregHolmes · 2026-01-19T13:15:00Z

src/pages/docs/chat/rooms/index.mdx


 To start receiving messages and events from a room, you need to attach to it. Attaching to a room tells Ably to start streaming messages to the client, and ensures that events are not missed in case of temporary network interruptions.

+<Aside data-type='see-evidence'>


I'm not too sure this Aside is where it should be. It's disconnecting the feature discussion of how to attach to a room.

GregHolmes · 2026-01-19T13:16:23Z

src/pages/docs/chat/rooms/media.mdx

 Upload the media to your own storage service, such as AWS S3, and then use the `metadata` field to reference the location of the media when a user [sends a message](/docs/chat/rooms/messages#send). On the receiving end, display the media to [subscribers](/docs/chat/rooms/messages#subscribe) that received the message.

+<Aside data-type='see-evidence'>
+Every message is redundantly stored across multiple isolated datacenters within your region before acknowledgment, preventing data loss. [See evidence here 🕵️](/docs/platform/architecture/fault-tolerance#core-layer)


I'm afraid I'm not too sure what is the point being gained here by talking about messages being redundantly stored on a share media page.

If it were relevant, it's unfortunately not really helpful as it's the first thing people will see when loading the page. They're here to learn about sharing media in a chat room.

GregHolmes · 2026-01-19T13:20:19Z

src/pages/docs/chat/rooms/reactions.mdx

 Room reactions are ephemeral and not stored or aggregated by Ably. The intention being that they show the overall sentiment of a room at a point in time.

+<Aside data-type='see-evidence'>
+Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here 🕵️](/docs/platform/architecture/latency#how-latency-is-measured)


I think latency talk is relevant for this page. But the positioning of the Aside may not be the greatest at the top of the page.

I will move to the bottom of the page where it says "Send a room reaction".

GregHolmes · 2026-01-19T13:21:53Z

src/pages/docs/chat/rooms/replies.mdx

 Message replies are implemented using the `metadata` field when you [send a message](/docs/chat/rooms/messages#send).

+<Aside data-type='see-evidence'>
+Applications maintain their state during disruptions. All messages are received in correct order with no message loss. [See evidence here 🕵️](/docs/platform/architecture/connection-recovery#message-identification-with-timeserial)


I think this may be relevant to the page, but the positioning may need to be rethought.

Move to the bottom of this section, below the code samples.

GregHolmes · 2026-01-19T13:23:31Z

src/pages/docs/chat/index.mdx

 * [Getting started: Chat in Kotlin (JVM)](/docs/chat/getting-started/jvm)
 * [Getting started: Chat in Swift](/docs/chat/getting-started/swift)

+<Aside data-type='see-evidence'>Ably monitors resource headroom and triggers automatic scaling when load approaches capacity, absorbing traffic spikes without degradation. [See evidence here 🕵️](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling)</Aside>


I don't think this page really needs an Aside. I'd recommend removing it from this page for now. The page needs a redesign (something on my list) and I think any stats you put in there may not be needed.

GregHolmes · 2026-01-19T13:25:00Z

src/pages/docs/guides/chat/build-livestream.mdx


 Ably is trusted by organizations delivering chat to millions of users in realtime. Its platform is engineered around the four pillars of dependability:

+<Aside data-type='see-evidence'>Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/scalability)</Aside>


I'm not sure the positioning of this is great. We're leading to the bullet points in the paragraph above, and then we place an Aside in the middle. cutting the flow of the experience in reading this page.

Move to the bottom of this section, below all the text on the diagram.

GregHolmes · 2026-01-19T13:25:42Z

src/pages/docs/guides/chat/build-livestream.mdx

 * **Server-side batching:** Reduce costs and network overhead by grouping messages before delivery. As shown in the [example](#server-side-batching), [batching messages](#server-side-batching) reduces the number of outbound messages such that it increases linearly with the number of users in the chatroom.
 * **Rate limiting:** Control the flow of messages per user to maintain readability and prevent spam. Choose between per-connection rate limits or global throttling.

+<Aside data-type='see-evidence'>With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/infrastructure-operations#resource-implications)</Aside>


I think this would be better further down the page at the end of this section and above the Authentication header. What do you think?

I have moved to the bottom of the bullet points in this section.

- Keep USP callout about edge network failures - Add jetpack language support to connection status docs 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

GregHolmes · 2026-01-21T13:29:06Z

I think we may need to re-think what these USPs are for. Currently the ones being added to the pages don't really make sense in the page they're in. It may be worth compiling a list of USPs we want to have.

Then going through page by page to see whether any of these USPs actually fit in that page or feel relevant for that page.

With key questions being asked each time:

Is the USP relevant to the page?
Does the positioning of the USP interrupt the actual content on the page? It's meant to be supporting the content on the page.

I'd also recommend that you get the new design ready in a new branch first and remove the ones in this PR (and the other PRs).

The table changes, although would be greatly welcome, do not belong in this PR, they just muddy the review and purpose of the task. I'd recommend cherry picking the changes out (as long as they're in their own commits), and putting them into a separate branch for a separate review.

franrob-projects · 2026-01-21T14:09:07Z

I think we may need to re-think what these USPs are for. Currently the ones being added to the pages don't really make sense in the page they're in. It may be worth compiling a list of USPs we want to have.

Then going through page by page to see whether any of these USPs actually fit in that page or feel relevant for that page.

With key questions being asked each time:

Is the USP relevant to the page?

Does the positioning of the USP interrupt the actual content on the page? It's meant to be supporting the content on the page.

I'd also recommend that you get the new design ready in a new branch first and remove the ones in this PR (and the other PRs).

The table changes, although would be greatly welcome, do not belong in this PR, they just muddy the review and purpose of the task. I'd recommend cherry picking the changes out (as long as they're in their own commits), and putting them into a separate branch for a separate review.

I will agree with the fact that these two can be removed, as we are really trying to push the architecture here and maybe are a little bit light on content:

setup.mdx "Ably automatically recovers connections and prevents message loss or duplication when clients reconnect within two minutes."Placed after the Logging section. The page is about SDK installation, authentication, and logging configuration—there's no discussion of connection recovery or reconnection behavior. This is exactly like the example you showed me earlier.
integrations.mdx "Ably delivers over 500 billion messages monthly, demonstrating large throughput capability."Placed in a section about decoding webhook messages. The content is about fromEncoded() methods and message mapping—throughput stats don't connect to this technical procedure.

and maybe:

typing.mdx "Ably achieves a global median message delivery latency of 37ms......."
reactions.mdx "Ably achieves a global median message delivery latency of 37ms......."

However, I would say that the others are in a reasonably good spot, and we are backing up the claim that we make with evidence in the architecture section...

In terms of supporting the actual documentation, I think that these have a slightly different purpose and it is more backing up. Therefore, a little bit of repetition is to be expected.

The purpose of this, it leans more into marketing and drawing people towards the architecture docs rather than adding more information about the functionality of the features that we're describing on the page...

Yes, we can remove the table fixes, although they were in a pretty poor state when I saw them. And thought I would just fix them here as i go..

GregHolmes · 2026-01-21T15:55:22Z

I will agree with the fact that these two can be removed, as we are really trying to push the architecture here and maybe are a little bit light on content:

setup.mdx "Ably automatically recovers connections and prevents message loss or duplication when clients reconnect within two minutes."Placed after the Logging section. The page is about SDK installation, authentication, and logging configuration—there's no discussion of connection recovery or reconnection behavior. This is exactly like the example you showed me earlier.

integrations.mdx "Ably delivers over 500 billion messages monthly, demonstrating large throughput capability."Placed in a section about decoding webhook messages. The content is about fromEncoded() methods and message mapping—throughput stats don't connect to this technical procedure.

and maybe:

typing.mdx "Ably achieves a global median message delivery latency of 37ms......."

reactions.mdx "Ably achieves a global median message delivery latency of 37ms......."

However, I would say that the others are in a reasonably good spot, and we are backing up the claim that we make with evidence in the architecture section...

In terms of supporting the actual documentation, I think that these have a slightly different purpose and it is more backing up. Therefore, a little bit of repetition is to be expected.

The purpose of this, it leans more into marketing and drawing people towards the architecture docs rather than adding more information about the functionality of the features that we're describing on the page...

Yes, we can remove the table fixes, although they were in a pretty poor state when I saw them. And thought I would just fix them here as i go..

I understand this but copying and pasting a couple sentences from another page doesn't really give you the understanding of how that supports or is relevant to the page in question. For example , on /docs/chat/rooms/reactions (room reactions), at the bottom you've got:

Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here 🕵️](https://ably-docs-ftf-315-write-ot90mk.herokuapp.com/docs/platform/architecture/latency#how-latency-is-measured)

Now, looking at it from someone who doesn't work at Ably, how does talking about 37ms latency help me understand or make my decision on using this feature within my chat app? Rewrite the sentence from a reactions perspective and then it makes sense.

I prompted Claude as possible ways to rewrite that sentence:

Specific usecase:
Realtime reactions that feel instant. When users react to a live moment, timing matters - a delayed reaction loses its meaning. Ably's 37ms global median latency ensures reactions arrive the moment they're sent, keeping your audience synchronized and engaged. [Learn how we measure latency →](https://ably.com/docs/platform/architecture/latency#how-latency-is-measured)

More concise:
Reactions need to feel instant to be meaningful. With Ably's 37ms global median latency, your users' emoji reactions arrive in the moment, not seconds after the action they're reacting to.

My point is they feel exactly how they are.. Copied and pasted from another section of the docs, with no context as to why they're here.

I think the first example above could possibly be too fluffy for our docs. Personally I prefer the second quote.

What do you think?

franrob-projects · 2026-01-21T17:17:46Z

I will agree with the fact that these two can be removed, as we are really trying to push the architecture here and maybe are a little bit light on content:

setup.mdx "Ably automatically recovers connections and prevents message loss or duplication when clients reconnect within two minutes."Placed after the Logging section. The page is about SDK installation, authentication, and logging configuration—there's no discussion of connection recovery or reconnection behavior. This is exactly like the example you showed me earlier.

integrations.mdx "Ably delivers over 500 billion messages monthly, demonstrating large throughput capability."Placed in a section about decoding webhook messages. The content is about fromEncoded() methods and message mapping—throughput stats don't connect to this technical procedure.

and maybe:

typing.mdx "Ably achieves a global median message delivery latency of 37ms......."

reactions.mdx "Ably achieves a global median message delivery latency of 37ms......."

However, I would say that the others are in a reasonably good spot, and we are backing up the claim that we make with evidence in the architecture section...
In terms of supporting the actual documentation, I think that these have a slightly different purpose and it is more backing up. Therefore, a little bit of repetition is to be expected.
The purpose of this, it leans more into marketing and drawing people towards the architecture docs rather than adding more information about the functionality of the features that we're describing on the page...
Yes, we can remove the table fixes, although they were in a pretty poor state when I saw them. And thought I would just fix them here as i go..

I understand this but copying and pasting a couple sentences from another page doesn't really give you the understanding of how that supports or is relevant to the page in question. For example , on /docs/chat/rooms/reactions (room reactions), at the bottom you've got:
Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here 🕵️](https://ably-docs-ftf-315-write-ot90mk.herokuapp.com/docs/platform/architecture/latency#how-latency-is-measured)
Now, looking at it from someone who doesn't work at Ably, how does talking about 37ms latency help me understand or make my decision on using this feature within my chat app? Rewrite the sentence from a reactions perspective and then it makes sense.

I prompted Claude as possible ways to rewrite that sentence:

Specific usecase: Realtime reactions that feel instant. When users react to a live moment, timing matters - a delayed reaction loses its meaning. Ably's 37ms global median latency ensures reactions arrive the moment they're sent, keeping your audience synchronized and engaged. [Learn how we measure latency →](https://ably.com/docs/platform/architecture/latency#how-latency-is-measured)

More concise: Reactions need to feel instant to be meaningful. With Ably's 37ms global median latency, your users' emoji reactions arrive in the moment, not seconds after the action they're reacting to.

My point is they feel exactly how they are.. Copied and pasted from another section of the docs, with no context as to why they're here.

I think the first example above could possibly be too fluffy for our docs. Personally I prefer the second quote.

What do you think?

Thank you for your feedback Greg..

I will rework these a bit more (without them sounding marketing)

Keep only USP aside additions and removals.

Adds USPs to chat docs

a49ddab

franrob-projects added the review-app Create a Heroku review app label Dec 23, 2025

ably-ci temporarily deployed to ably-docs-ftf-315-write-dp8dpg December 23, 2025 16:08 Inactive

franrob-projects and others added 2 commits January 9, 2026 13:56

Merge branch 'main' into FTF-315-write-usp-copy-for-chat

3b4b551

franrob-projects requested a review from m-hulbert January 9, 2026 13:59

franrob-projects closed this Jan 9, 2026

franrob-projects reopened this Jan 9, 2026

franrob-projects marked this pull request as ready for review January 9, 2026 14:02

franrob-projects removed the review-app Create a Heroku review app label Jan 9, 2026

franrob-projects temporarily deployed to ably-docs-ftf-315-write-pgope8 January 9, 2026 14:03 Inactive

franrob-projects requested a review from GregHolmes January 9, 2026 14:42

franrob-projects added the review-app Create a Heroku review app label Jan 12, 2026

GregHolmes requested changes Jan 19, 2026

View reviewed changes

Addresses feedback from review

541b73d

franrob-projects added review-app Create a Heroku review app and removed review-app Create a Heroku review app labels Jan 21, 2026

franrob-projects requested a review from GregHolmes January 21, 2026 11:58

Resolve merge conflicts with main

ac4b7f7

- Keep USP callout about edge network failures - Add jetpack language support to connection status docs 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

franrob-projects temporarily deployed to ably-docs-ftf-315-write-ot90mk January 21, 2026 12:31 Inactive

Revert table formatting changes from USP branch

a5e36d4

Keep only USP aside additions and removals.

franrob-projects temporarily deployed to ably-docs-ftf-315-write-ot90mk January 22, 2026 12:37 Inactive

Merge branch 'main' into FTF-315-write-usp-copy-for-chat

2429a41

franrob-projects deployed to ably-docs-ftf-315-write-ot90mk January 22, 2026 12:42 View deployment


		![Ably Chat React App](../../../../images/examples/chat-ui-app.png)

		<Aside data-type='see-evidence'>


		The history feature enables users to retrieve messages that have been previously sent in a room. Ably stores chat messages for 30 days by default. You can extend this up to 365 days by [contacting us](https://ably.com/support).

		## Retrieve previously sent messages <a id="history"/>


		To start receiving messages and events from a room, you need to attach to it. Attaching to a room tells Ably to start streaming messages to the client, and ensures that events are not missed in case of temporary network interruptions.

		<Aside data-type='see-evidence'>


		Ably is trusted by organizations delivering chat to millions of users in realtime. Its platform is engineered around the four pillars of dependability:

		<Aside data-type='see-evidence'>Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/scalability)</Aside>

Adds USPs to chat docs #3056

Are you sure you want to change the base?

Adds USPs to chat docs #3056

Uh oh!

Conversation

franrob-projects commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

coderabbitai bot commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

GregHolmes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GregHolmes commented Jan 21, 2026

Uh oh!

franrob-projects commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GregHolmes commented Jan 21, 2026

Uh oh!

franrob-projects commented Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

franrob-projects commented Dec 23, 2025 •

edited

Loading

coderabbitai bot commented Dec 23, 2025 •

edited

Loading

franrob-projects commented Jan 21, 2026 •

edited

Loading