Improve documentation to ensure devs know when to use REST vs Realtime SDKs

[mattheworiordan]

A frequent problem our customer support team deal with is the fact that customers use Realtime SDKs server-side when it's not a good fit. See https://support.ably.io/support/solutions/articles/3000060319-should-i-use-the-rest-or-realtime-library-. Using a Realtime SDK just for publishing messages from servers in most cases is not ideal because:

• It takes longer to publish a message typically as a connection needs to be established, a channel needs to be attached, and a message published. Whilst we do support transient publishing, most devs don't know about this.
• Customers hit concurrent channel limits per connection when they share the Ably Realtime object and don't realise they need to detach channels.
• Customers ultimately will hit per connection message throughput limits as the volumes increase, and without them building their own connection pooling capabilities, there is no easy fix for this. Connection pooling is not easy.
• Idempotency support is harder and less obvious.
• Publish retries will end up going to the same server unless the connection fails too, meaning in some cases publishes are less fault tolerant.
• Transient publishing is not obvious to developers anyway as a way around some of the shortfalls of using a realtime connection for publishing.

I believe we need to:

• Push forward with HTTP/2 support as it is better suited to high volumes of stateless message publishing - https://ably.atlassian.net/browse/SDK-4, and Prefer HTTP/2 when available ably-ruby#197
• Figure out why developers who come to Ably don't realise that using a Realtime SDK server-side in most cases is not preferable. This is definitely a documentation issue. We touch on this in https://www.ably.io/documentation/best-practice-guide, but it's either inadequate or clearly not read.
• Review how our batch and transient publishing fits into this requirement - Batch / Transient publishing docs are inadequate #684
• Consider adding the publish method on the root Ably object as a means to a) explain why this method exists, b) fix the unintuitive channel attached problem, c) lead customers better to the right solution for nodes that publish primarily.

cc @paddybyers @QuintinWillison because this is not just a docs issue, it's an SDK issue too IMHO.
cc @JackUkleja @kavalerov because if it's an SDK issue, then it's a product issue :)
cc @Ugbot because we need to figure out how this information does not get lost in customer support conversations. This is a recurring problem yet so far no one has raised it as an ongoing issue that needs to be addressed. In the new world of DevRel running 2nd line support, I would like you to have a think about how this info is captured and relayed to product & Mark. See https://support.ably.io/a/tickets/106291

┆Issue is synchronized with this Jira Task by Unito

[MarkWoulfeAbly]

For me this falls into two buckets:

1. Product marketing - As a noob coming to the platform I assumed that all we did was realtime, it's the name of the company! Maybe others are falling into that trap and diving straight into the realtime implementation without giving it much thought.

2. Documentation/discovery - We should probably have a documentation page titled 'REST Vs Realtime' to make it clear as day. As you mentioned @mattheworiordan we already have some of that content in best practice guide and the download page. We could flesh that content out and add it as a standalone page.

[mattheworiordan]

Maybe others are falling into that trap and diving straight into the realtime implementation without giving it much thought.

Well I don't think our Product Marketing should drop Realtime because that is what we do as a business. We also support SSE, MQTT, etc. So I am not sure I agree with that thinking I am afraid. Product Marketing gets people to Ably, Developer DX & Docs take over from the point they sign up / try out the APIs.

We should probably have a documentation page titled 'REST Vs Realtime' to make it clear as day

We do https://support.ably.io/a/solutions/articles/3000060319 (standalone) and in best practice guide and in docs. I am not convinced that alone with solve the issue however. I think we need to understand the journey better, and make sure we're addressing this question as part of that developer journey from sign up to using our APIs.

[mattheworiordan]

Another customer having this same problem calling our Realtime SDK from a Lambda - https://ably.freshdesk.com/a/tickets/107281

[kavalerov]

I think we need to understand the journey better, and make sure we're addressing this question as part of that developer journey from sign up to using our APIs.

This is a very good point - we need to understand the journey better, to be able to improve it.

Regarding this specific problem - I think one more source of the confusion is also the terminology we are using: our SDKs are called "client libraries", "libraries", "client libraries SDKs" and "SDKs" in different places on the website.
The docs also say Ably’s realtime client libraries are most commonly used client-side and Ably’s REST libraries are most commonly used server-side, but then we again group them together under "libraries".

I am wondering (and I don't know the answer to this yet) if we should change our approach, and name SDKs based on their intended use rather than what they are under the hood: for example, use something like "Ably realtime client SDKs" and "Ably REST server-side SDKs". @MarkWoulfeAbly @mattheworiordan what do you think?

[paddybyers]

If we're looking at this terminology, also bear in mind that there are multiple examples of there being an Ably REST library and an Ably Realtime library in the same distribution. (That is, the same module/package reference, in the public repositories for the platform in question.) So is that one or two SDKs ?

[kavalerov]

This is a very good point @paddybyers .

Just to make sure I understand the decision making behind this:
The reason Realtime and REST are combined in a same distribution is because the original intent was to give full set of Ably capabilities to developers who use certain language, and avoid the confusion of "I have downloaded the wrong SDK"?

[paddybyers]

Anyone using the realtime API also will likely need to use the REST API, so you have to have one library containing both. Yes, unless there was a specific concern about the footprint of the library, or complications arising from some of the realtime dependencies, there's the no real need to create an additional distribution containing just the REST library.

[mattheworiordan]

I think one more source of the confusion is also the terminology we are using: our SDKs are called "client libraries", "libraries", "client libraries SDKs" and "SDKs" in different places on the website.
The docs also say Ably’s realtime client libraries are most commonly used client-side and Ably’s REST libraries are most commonly used server-side, but then we again group them together under "libraries".

Note that we explicitly state "We refer to our SDKs or client libraries always as Client library SDKs." in our Tone of voice guidelines.

I am wondering (and I don't know the answer to this yet) if we should change our approach, and name SDKs based on their intended use rather than what they are under the hood: for example, use something like "Ably realtime client SDKs" and "Ably REST server-side SDKs".

We've thought about this extensively (that is what Pusher does), and in the end refrained from this because Realtime SDKs can be used on servers, and REST SDKS can be used on clients. What is a client anyway, a client of Ably, or a client device? I definitely recognise that in most cases REST is used server-side, and Realtime is used on devices, but that's not always the case :(

Yes, unless there was a specific concern about the footprint of the library, or complications arising from some of the realtime dependencies, there's the no real need to create an additional distribution containing just the REST library.

Exactly, Realtime is always a superset of REST. And when it comes to distributions and "weight" of the SDKs, you can see that for Ruby, we have a REST only lib at https://rubygems.org/gems/ably-rest (which avoids all Realtime dependencies), and Realtime & Rest as https://rubygems.org/gems/ably.

[kavalerov]

We've thought about this extensively (that is what Pusher does), and in the end refrained from this because Realtime SDKs can be used on servers, and REST SDKS can be used on clients. What is a client anyway, a client of Ably, or a client device? I definitely recognise that in most cases REST is used server-side, and Realtime is used on devices, but that's not always the case :(

Hm. I see your point. At the same time, I think we can also be strongly opinionated about this, and make this distinction ourself. This will not make it impossible, for example, to use REST SDK on client, devs will still be able to do that, but it will make it crystal clear that intended use of the REST SDK is server side.

[ably-sync-bot]

➤ Mark Hulbert commented:

This issue has accumulated several different streams of work from when it was raised.

From a documentation perspective: the best practice guide section has been updated since this was raised. I’m more than happy to cover any specific changes on the current version in separate issues, but closing this one for now. Also tagging Gino Toro for visibility on the developer journey comments given your current work stream.

From an SDK perspective: I believe everything is captured in separate issues or tickets already, but flagging Quintin Willison in case anything has been missed.