USPs for Pub/Sub #3043

franrob-projects · 2025-12-18T14:17:32Z

This PR:

Extracts USPs from /docs/platform/architecture.
- Uses UPSs to supplement Pub/Sub docs with evidence (on the Ably platform) to the claims we make about the product.
Uses a place-holder "evidence" component (while the design team finishes the official one).

Jira

FTF-314

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-18T14:21:07Z

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.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch FTF-314-write-usp-copy-for-pub-sub

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.}

paddybyers · 2025-12-19T09:48:29Z

src/pages/docs/connect/states.mdx

 Although connection state is temporary, Ably provides continuity of message delivery between a client and the service provided that a dropped connection is re-established by the client within a limited interval (typically around two minutes). After that time the connection becomes stale and the system will not attempt to recover the connection state.

+<Aside data-type='see-evidence'>
+Failed connections automatically try up to 6 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)


Suggested change

Failed connections automatically try up to 6 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)

Failed connections automatically try up to 5 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)

paddybyers · 2025-12-19T09:49:13Z

src/pages/docs/getting-started/index.mdx

 These are your first steps towards building a realtime application that can effortlessly scale to serve millions of users.

+<Aside data-type='see-evidence'>
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/latency#latency)


Which specific metric on that page does this refer to?

I think this is a bit intrusive on an index of getting started guides.

paddybyers · 2025-12-19T09:50:31Z

src/pages/docs/presence-occupancy/presence.mdx

 | Leave | A member who was present has now left the channel. This may be a result of an explicit request to leave or implicitly when detaching from the channel. Alternatively, if a member's connection is abruptly disconnected and they do not resume their connection within a minute, Ably treats this as a leave event as the client is no longer present |
+
+<Aside data-type='see-evidence'>
+In catastrophic datacenter failures, Ably automatically reroutes all traffic in under 2 minutes, maintaining service continuity. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)


I don't think this is an accurate representation of what that link says

Ably's edge network bypasses DNS entirely when clients can't reach primary endpoints. SDKs automatically reconnect to backup endpoints instead of waiting several minutes for DNS make changes.

paddybyers · 2025-12-19T09:52:19Z

src/pages/docs/push/index.mdx

 Push notifications notify user devices or browsers regardless of whether an application is open and running. They deliver information, such as app updates, social media alerts, or promotional offers, directly to the user's screen. Ably sends push notifications to devices using [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) or [Apple Push Notification Service](https://developer.apple.com/notifications/), and to browsers using [Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). Push notifications don't require a device or browser to stay connected to Ably. Instead, a device's or browser's operating system or web browser maintains its own battery-efficient transport to receive notifications.

+<Aside data-type='see-evidence'>
+Trust 99.999% uptime with just 5 minutes of downtime per year, ensuring your realtime features are always available. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/infrastructure-operations.mdx)


The SLA doesn't imply how much downtime there will be. If defines the threshold for the amount of downtime that triggers compensation. As written, this makes it sound like we're ok with 5 minutes, and customers should expect that.

I will remove this. We only cover this in "at a glance".

Note
I'd like to expand on... the 4 pillars in the docs. Possibly in the /platform/architecture
Leading on from the UPS work

This would have supported this metric better (in addition to the tweak in writing).

paddybyers · 2025-12-19T09:57:29Z

src/pages/docs/auth/identified-clients.mdx

 For example, assume you are building a chat application and want to allow clients to publish messages and be present on a channel. If each client is assigned a trusted identity by your server, such as a unique email address or UUID, then all other subscribed clients can trust any messages or presence events they receive in the channel as being from that client. No other clients are permitted to assume a `clientId` that they are not assigned in their Ably-compatible token. They are unable to masquerade as another `clientId`.

+<Aside data-type='see-evidence'>
+Message processing is designed to be transactional, therefore messages are either fully processed or not processed at all, preventing data corruption. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/fault-tolerance#core-layer)


I'm not really sure what this is trying to say. Is it saying that a single message is processed atomically, or multiple messages are processed atomically. And I'm unsure how this claim relates to the surrounding text.

I'll remove entirely (this one was a bot far fetched).

paddybyers · 2025-12-19T09:59:21Z

src/pages/docs/channels/options/deltas.mdx

 There is no constraint on how many publishers or subscribers there are. If there are multiple publishers, then deltas can still be generated, and they will be determined based on the order of messages. Deltas are calculated strictly based on the message ordering in that channel, with the effectiveness being dependent on the level of similarity between successive payloads.

+<Aside data-type='see-evidence'>
+Subscribers on that channel anywhere in the world will receive those messages in the same order they were originally published. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/message-ordering)


This comment refers to "that channel" and "those messages", but it's unclear what it's referring to based on the surrounding text.
If this is stating that all subscribers globally see messages in the same order, for a given channel, then that's not true. So let's revisit this claim and decide what we need to say.

Messages published using Realtime have consistent ordering for all subscribers, with each message assigned a unique serial number to preserve its place.

m-hulbert

I'm part way through, but I think you need to review the positioning and relevance of all of these, please.

If you load the review app a number of them are splitting up descriptions and explanations. Others are unrelated to the topics on the page, which make them quite intrusive to a reader at the moment. I appreciate that may be lessened by a fully designed (or more minimal) component, but it's still worth reviewing them.

URLs are fully qualified when they don't need to be.

m-hulbert · 2025-12-21T13:44:42Z

src/pages/docs/auth/revocation.mdx

 The token revocation API is rate-limited, so there is a maximum global aggregate rate of revocation requests per app. The rate is configurable by Ably at the application level. As part of the process of enabling revocation on an app Ably will ask you what the maximum rate of token revocations on that app needs to be, and then provision that capacity. The decision is not permanent, it can be changed by Ably on request at any time.

+<Aside data-type='see-evidence'>
+By tracking changes over time, Ably can identify gradual degradations before they become critical issues. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/infrastructure-operations#metrics-collection)


This USP is a bit vague in general as I'm not sure what we're tracking over time. Similarly it seems a bit irrelevant to token revocation when I follow this link.

m-hulbert · 2025-12-21T13:45:51Z

src/pages/docs/channels/index.mdx

 | Message annotations, updates, and deletes | If enabled, allows message "annotations":/docs/messages/annotations to be used, as well as updates and deletes to be published to messages. Note that these features are currently Experimental, still in development, and subject to change. When this feature is enabled, messages will be "persisted":/docs/storage-history/storage#all-message-persistence (necessary in order from them later be annotated or updated), and "continuous history":/docs/storage-history/history#continuous-history features will not work.

+<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)


The positioning of this is a little odd in the middle of a section around rules.

m-hulbert · 2025-12-21T13:47:00Z

src/pages/docs/channels/options/index.mdx

 [Occupancy](/docs/presence-occupancy/occupancy) provides metrics about the clients attached to a channel, such as the number of connections and the number of clients subscribed to the channel. `occupancy` can be specified in the `params` property in order to subscribe a client to occupancy metrics for the channel. The metrics will be received by a client as events on the channel.

+<Aside data-type='see-evidence'>
+Metrics are collected from the host instance and from each of the containers on every instance, providing comprehensive visibility into system performance and resource utilization. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/infrastructure-operations#metrics-collection)


System metrics are different to the metrics returned by occupancy which are related solely to that channel.

m-hulbert · 2025-12-21T13:49:44Z

src/pages/docs/channels/options/rewind.mdx

 If the attachment is successful, and one or more messages exist on the channel prior to the present position, then those messages will be delivered to the subscriber immediately after the attachment has completed, and before any subsequent messages that arise in real time.

+<Aside data-type='see-evidence'>
+Timeserials enable precise positioning within a message stream, allowing clients to resume connections from exactly where they left off. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/message-ordering#timeserials-tracking-position-in-message-streams)


This is perhaps more relevant to resume than rewind.

m-hulbert · 2025-12-21T13:51:07Z

src/pages/docs/channels/states.mdx

 });
 ```

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


This is wrapped in the middle of a codeblock so it won't be rendered. Similarly it doesn't seem related to channel state.

m-hulbert · 2025-12-21T13:53:16Z

src/pages/docs/connect/index.mdx

 If a connection to Ably is not explicitly closed when there is a page unload event, then the connection state is preserved by Ably for 2 minutes. Preserving connection state for 2 minutes when there is an unexpectedly dropped connection provides the opportunity for the client to reconnect and resume the connection without losing any messages.

+<Aside data-type='see-evidence'>
+Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)


The other USP you've put on this page seems more relevant here.

m-hulbert · 2025-12-21T13:55:12Z

src/pages/docs/getting-started/index.mdx

 These are your first steps towards building a realtime application that can effortlessly scale to serve millions of users.

+<Aside data-type='see-evidence'>
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/latency#latency)


I think this is a bit intrusive on an index of getting started guides.

m-hulbert · 2025-12-21T13:56:07Z

src/pages/docs/messages/batch.mdx

 * Each `BatchSpec` will only count as a single message for the purpose of the [per-channel rate limit](/docs/platform/pricing/limits#message)

+<Aside data-type='see-evidence'>
+Build with confidence on industry-leading quality of service guarantees that ensure message integrity, ordering, and delivery. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/message-ordering)


This positioning is a bit out of place as it's interrupting an explanation and doesn't relate to batching.

franrob-projects requested review from GregHolmes and removed request for GregHolmes December 18, 2025 17:00

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

ably-ci temporarily deployed to ably-docs-ftf-314-write-uuqptb December 18, 2025 17:07 Inactive

franrob-projects changed the title ~~Adds placeholder USP component~~ USPs for Pub/Sub Dec 18, 2025

franrob-projects added 5 commits December 19, 2025 10:33

Adds placeholder USP component

672707d

Adds PERFORMANCE USPs to Pub/Sub

22075f4

Adds RELIABILITY USPs to Pub/Sub

f926abe

Adds SCALE USPs to Pub/Sub

1d2b726

Specifes URLs

ac45425

franrob-projects force-pushed the FTF-314-write-usp-copy-for-pub-sub branch from efa1295 to 3944169 Compare December 19, 2025 09:33

franrob-projects temporarily deployed to ably-docs-ftf-314-write-uuqptb December 19, 2025 09:34 Inactive

Adds INFRA USPs to Pub/Sub

3d5033d

franrob-projects force-pushed the FTF-314-write-usp-copy-for-pub-sub branch from 047a0df to 3d5033d Compare December 19, 2025 09:40

franrob-projects temporarily deployed to ably-docs-ftf-314-write-uuqptb December 19, 2025 09:40 Inactive

franrob-projects requested review from GregHolmes and m-hulbert December 19, 2025 09:42

paddybyers reviewed Dec 19, 2025

View reviewed changes

franrob-projects marked this pull request as ready for review December 19, 2025 10:14

m-hulbert reviewed Dec 21, 2025

View reviewed changes

Addresses feedback

6f16dd7

franrob-projects temporarily deployed to ably-docs-ftf-314-write-uuqptb December 22, 2025 15:01 Inactive

	Failed connections automatically try up to 6 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)
	Failed connections automatically try up to 5 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)

USPs for Pub/Sub #3043

Are you sure you want to change the base?

USPs for Pub/Sub #3043

Uh oh!

Conversation

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

Uh oh!

Jira

Checklist

Uh oh!

coderabbitai bot commented Dec 18, 2025

Review skipped

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!

m-hulbert 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!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

5 participants

franrob-projects commented Dec 18, 2025 •

edited by atlassian bot

Loading