docs icon indicating copy to clipboard operation
docs copied to clipboard

Old Ably diagrams are confusing

Open mattheworiordan opened this issue 2 years ago • 1 comments

See https://ably.com/docs/core-features/pubsub and https://ably.com/docs/core-features/channels#understanding-decoupled-clients, both of them use this diagram:

MO screenshot 2022-07-17 at 20 39 01

I honestly have no idea what this diagram is trying to show users.

Given this is our Concepts documentation, so arguably the first stop for users who need to understand what a channel / pub/sub is, I believe we're setting new users up for confusion as opposed to clarity.

Looking through the docs more widely, I think a lot of the diagrams are dated and ineffective (using old styles, but more importantly, conceptually not strong). We have an opportunity to really show people quickly how Ably works in our concept docs, and arguably to some degree even in our SDK docs in the intro sections. We should strive to use richer media (GIFs, interactivity, clear diagrams etc.)

┆Issue is synchronized with this Jira Task by Unito

mattheworiordan avatar Jul 17 '22 20:07 mattheworiordan