ably-sync-bot
commented
2 years ago ➤ Tony Bedford commented:
Steven Appleby - we should come up with a better diagram, and then work with Leonie Wharton to create one that conforms to our branding and style guidelines. I would create an initial idea in Google diagrams (or whatever), and then share in topic-deved for feedback from the team. Bruce Thomas may also be able to help with this one too. Note: this ticket should focus on the diagram that was initially identified in this bug report, as we have the diagrams epic to deal with the wider work of improving diagrams generally.
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:
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