Batch / Transient publishing docs are inadequate

[mattheworiordan]

Customers have asked about batch publishing a few times (see https://support.ably.io/a/tickets/100659 for example), and what I've noticed is that:

• We make almost no mention of it anywhere a developer may look for this. See the REST publish docs - https://www.ably.io/documentation/rest/messages#message-publish. No mention of batch, bulk or transient publishing. Same applies to realtime publish docs https://www.ably.io/documentation/realtime/messages#message-publish.
• The channel docs https://www.ably.io/documentation/rest/channels at least mention the batch API, but in the getting started section. So a user who finds the publish method, has no way of knowing how they can do batch/bulk operations, or how indeed they could consider using transient publishing at all. The realtime channel docs are similar, mentioning transient publishing, but no mention of the batch API which has some advantages over transient publishing (one message to many channels for example).
• Going to the REST API docs at https://www.ably.io/documentation/rest-api makes no mention of batch/bulk publishing. There is a small note about a beta API existing, but a) it's not obvious, b) we can't expect people to explore all our docs to find important info, c) we should mention the bulk/batch API near to where people may be looking/learning.
• Support FAQs are inadequate (non-existent largely) - see below

Whilst reviewing all of this, I saw lots of issues that I marked up:

┆Issue is synchronized with this Jira Bug by Unito

[mattheworiordan]

In addition, support FAQs and search for common answers to bulk/batch publishing questions is inadequate.

[paddybyers]

• See the REST publish docs - https://www.ably.io/documentation/rest/messages#message-publish. No mention of batch, bulk or transient publishing

Transient publishing is nothing to do with REST

[mattheworiordan]

Transient publishing is nothing to do with REST

Of course it's not. But the point is that a developer doesn't think about transient publishing, they don't even know what it is.

A developer thinks about their problem which is, for example, "I need to publish lots of messages", or I need to publish one message to many channels". So they think of bulk publishing, or batch publishing, and transient publishing for a realtime client offers high performance publishing on a single connection that is effective for bulk publishing, and often batch publishing if one message only goes to one channel.

So our documentation continues to be written from our perspective in regards to how we've designed and described our APIs, instead of around the problems developers have enabling them to discover our feature set that helps them solve their problems.

I don't think you could say that anyone, other than Ably, would have any idea what "transient publishing" is without reading the docs. And that's my point.

[ndastur]

Hi Guys. Any progress on this. I remember reporting that transient publishing didn't seem to be available in the .Net SDK. It remains listed on the feature matrix as available, but this was previously an docs error.
Also on https://www.ably.io/documentation/rest/messages#message-publish there is only a JS example for idempotent publishing. Is it not supported on .Net either? BTW having a JS example in the .Net docs risks a dev copying that sample code thinking it will work in .Net

[paddybyers]

Reopening. @QuintinWillison pls have a look ^.