docs: readme trim and getting started #223
Conversation
We consider the docs site to be the source of truth for our documentation (outside of inline documentation). This change follows the steps already taken by JS to remove the extra information from the README.
WalkthroughThe pull request updates the Changes
Sequence Diagram(s)sequenceDiagram
participant U as User
participant D as Documentation
participant S as Ably Chat SDK
U->>D: Reads "Getting Started" guide
D->>S: Instructs client initialization
U->>S: Creates chat room
U->>S: Sends a message
S-->>U: Returns success with a congratulatory message
Possibly related PRs
Suggested reviewers
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
github-actions
bot
temporarily deployed
to
staging/pull/223/AblyChat
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
README.md (3)
88-89: Refine introductory guidance text.
The phrase "First of all," is somewhat redundant. Consider simplifying the sentence to improve clarity. For example, you might change it to:-First of all, start by creating a Swift project and installing the Chat SDK using the instructions described above. Next, replace the contents of your `main.swift` file with +Start by creating a Swift project and installing the Chat SDK using the instructions described above. Then, replace the contents of your `main.swift` file with
91-145: Ensure the code snippet clarity and context.
The provided Swift code example is well-organized and demonstrates key concepts like initializing the Ably Chat client, attaching to a room, and sending a message. A couple of suggestions:
- Consider adding a brief inline comment about the use of
Task {}for asynchronous operations, as this may need highlighting for developers new to Swift concurrency.- It might be useful to note that error handling is simplified for this example and that production code should include robust error management.
147-163: Specify a language for the console output fenced code block.
For better clarity and to adhere to markdown linting guidelines, add a language identifier (e.g.,textorconsole) to the fenced code block showing the expected terminal output. For example:-``` +```text🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
155-155: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~87-~87: Often, this adverbial phrase is redundant. Consider using an alternative.
Context: ...at client and sent your first message. First of all, start by creating a Swift project and ...
(FIRST_OF_ALL)
🪛 markdownlint-cli2 (0.17.2)
README.md
155-155: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms (6)
- GitHub Check: Example app, tvOS (Xcode 16)
- GitHub Check: Example app, iOS (Xcode 16)
- GitHub Check: Example app, macOS (Xcode 16)
- GitHub Check: Xcode, tvOS (Xcode 16)
- GitHub Check: Xcode, iOS (Xcode 16)
- GitHub Check: Xcode, macOS (Xcode 16)
🔇 Additional comments (3)
README.md (3)
84-84: Clarify the "Getting Started" section header.
The addition of the "## Getting Started" section clearly signals the new focus of this guide. This makes the document structure more intuitive for newcomers.
86-86: Clear tutorial objective stated.
Stating that the tutorial will help users initialize the client and send their first message is concise and effective.
165-166: Concluding message is concise and encouraging.
The congratulatory note effectively wraps up the tutorial, reinforcing user success.
This change includes a basic getting-started guide intended to guide users through their first steps with Ably Chat to sending their first message. This will be replicated in the website dashboard in time.
AndyTWF
force-pushed
the
readme-getting-started
branch
from
cb9d9a2 to
20d5a76
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
README.md (2)
84-89: Clear Introduction in the “Getting Started” Section with a Minor Nitpick
The new “Getting Started” section provides a concise and user-friendly introduction to the SDK. However, the phrase “First of all” (line 86) comes across as redundant. Removing or rephrasing this phrase could tighten the prose and improve clarity.🧰 Tools
🪛 LanguageTool
[style] ~87-~87: Often, this adverbial phrase is redundant. Consider using an alternative.
Context: ...at client and sent your first message. First of all, start by creating a Swift project and ...(FIRST_OF_ALL)
147-163: Script Execution Instructions and Expected Output Formatting
The “Now run your script” section and the subsequent expected output block are nicely laid out, offering an end-to-end walkthrough. To adhere to markdownlint guidelines (MD040), specify a language identifier for the expected output fenced code block—for example, use “plaintext” instead of a plain “” for the block starting at line 155.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
155-155: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~87-~87: Often, this adverbial phrase is redundant. Consider using an alternative.
Context: ...at client and sent your first message. First of all, start by creating a Swift project and ...
(FIRST_OF_ALL)
🪛 markdownlint-cli2 (0.17.2)
README.md
155-155: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms (10)
- GitHub Check: Example app, tvOS (Xcode 16)
- GitHub Check: Example app, iOS (Xcode 16)
- GitHub Check: Xcode,
releaseconfiguration, tvOS (Xcode 16) - GitHub Check: Example app, macOS (Xcode 16)
- GitHub Check: Xcode,
releaseconfiguration, iOS (Xcode 16) - GitHub Check: Xcode,
releaseconfiguration, macOS (Xcode 16) - GitHub Check: Xcode, tvOS (Xcode 16)
- GitHub Check: Xcode, iOS (Xcode 16)
- GitHub Check: SPM (Xcode 16)
- GitHub Check: Xcode, macOS (Xcode 16)
🔇 Additional comments (2)
README.md (2)
91-145: Well-Structured Code Snippet Demonstrating Modern Swift Concurrency
The code sample is clear and effectively demonstrates key steps such as initializing the Ably Chat client, subscribing to connection state changes, attaching to a chat room, and sending a message using Swift’s async/await constructs. As an optional improvement, consider adding a brief inline comment explaining the async/await usage (for example, noting thatTask { ... }is used to handle asynchronous events) to help developers who may be newer to Swift concurrency.
1-3: Overall Documentation Enhancement
The trimmed README and the added Getting Started guide are well aligned with the PR objectives. These changes streamline the documentation, making it clear that the online documentation site is the definitive reference while also providing a practical introductory guide for new users.Also applies to: 164-179
This change incorporates the following changes:
CHA-841
CHA-819
I'd recommend reviewing by viewing the rendered markdown in GitHub - the diff is quite large!
Summary by CodeRabbit