Skip to content
This repository was archived by the owner on Aug 10, 2026. It is now read-only.

[DX-955] Add use-case based SDK references across Pub/Sub pages - #3340

Open
sacOO7 wants to merge 11 commits into
mainfrom
fix/incorrect-pubsub-sections
Open

[DX-955] Add use-case based SDK references across Pub/Sub pages#3340
sacOO7 wants to merge 11 commits into
mainfrom
fix/incorrect-pubsub-sections

Conversation

@sacOO7

@sacOO7 sacOO7 commented Apr 16, 2026

Copy link
Copy Markdown
Contributor
  • Fixes https://ably.atlassian.net/browse/DX-955
  • During chat-poc, LLM suggested to use pub-sub SDK to build chat app instead of core chat SDK.
  • Pub/Sub documentation pages currently frame core primitives (presence, annotations, channels) as the primary way to build chat features like reactions, typing indicators, and chat rooms — without mentioning that the Chat SDK and Spaces SDK provide purpose-built APIs for these use cases. This misleads developers into building from scratch on Pub/Sub when dedicated SDKs exist. Additionally, several pages contain broken anchors, legacy textile syntax, inconsistent naming, and stale notices.
  • Clarified that Pub/Sub should be used for custom features not covered by purpose-built SDKs.
  • Added a link to the product guidance page for choosing the right Ably product.

Changes

SDK cross-references (prevent misguided implementations):

  • Add Chat SDK/Spaces SDK asides on annotations, presence, presence-occupancy overview, Pub/Sub
    basics, data streaming guide, and dashboards guide pages
  • Link inline mentions of "chat rooms", "typing indicators", "avatar stacks", and "emoji reactions"
    to the appropriate SDK docs

Broken links fixed:

  • /docs/channels#publish/docs/pub-sub#publish in push FAQs (2 instances)
  • /docs/storage-history/storage#persistence/docs/storage-history/storage#all-message-persistence
    in dashboards guide
  • /docs/metadata-stats/stats#live/docs/metadata-stats/stats#app-meta in data streaming guide
  • Textile-style links ("text":/path) → MDX links ([text](/path)) in channels index, plus typo fix

Naming and consistency:

  • Replace chatroom/private:chatroom channel names with my-channel/private:my-channel across
    channel states (~20 instances) and Pub/Sub advanced (~20 instances) to avoid implying Pub/Sub
    channels are for building chat
  • Fix "PubSub" → "Pub/Sub" in Chat message reactions page
  • Replace placeholder API keys (your-api-key, YOUR_API_KEY_NAME) with template variables
    ({{API_KEY}}, {{API_KEY_NAME}}, {{API_KEY_SECRET}}) in both Pub/Sub guides

Stale notice:

  • Wrap plain-text subscription filters preview notice in proper <Aside data-type='public-preview'>
    block for consistency

Loading
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

review-app Create a Heroku review app

Development

Successfully merging this pull request may close these issues.

6 participants