docs(community): update latest community documentation #3821
Conversation
asyncapi-bot
requested review from
Mayaleeeee,
TRohit20,
akshatnema,
anshgoyalevil,
asyncapi-bot-eve,
derberg and
quetzalliwrites
as code owners
WalkthroughThis pull request updates the community documentation and configuration by adding new guides and style guidelines. A new entry for the community style guide is appended in the JSON configuration. Additionally, three sets of markdown documents are introduced: onboarding guides for AsyncAPI Ambassadors and Maintainers, and style guide documents covering formatting, punctuation, and voice and tone. Changes
Possibly related PRs
Suggested reviewers
Poem
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 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
Documentation and Community
|
asyncapi-bot
requested review from
Aahil13,
VaishnaviNandakumar,
ashmitjsg and
sambhavgupta0705
❌ Deploy Preview for asyncapi-website failed.
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #3821 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 21 21
Lines 667 667
Branches 113 113
=========================================
Hits 667 667 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![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 (8)
markdown/docs/community/styleguide/punctuation.md (4)
27-27: Consider using “semicolon” as a single word.
The heading “## 3. Semi-colon (;)” could be revised to “## 3. Semicolon (;)” for consistency with standard spelling conventions.🧰 Tools
🪛 LanguageTool
[misspelling] ~27-~27: This word is normally spelled as one.
Context: ...e guides or personal preference. ## 3. Semi-colon (;) Use a semicolon to separate two in...(EN_COMPOUNDS_SEMI_COLON)
43-46: Punctuation improvements for dash examples.
On line 43, consider inserting a comma after “sentence” to improve readability, and on line 46, change “brand new” to “brand‐new” so the compound adjective is correctly hyphenated.🧰 Tools
🪛 LanguageTool
[uncategorized] ~43-~43: Possible missing comma found.
Context: ...tes a sudden break or interruption in a sentence or provides emphasis. Some examples inc...(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~46-~46: ‘brand new’ seems to be a compound adjective before a noun. Use a hyphen: “brand-new”.
Context: ...." - "She received an unexpected gift—a brand new car!" A hyphen (-) joins compound ...(CA_BRAND_NEW)
53-58: Vary sentence structure in the Style Tips section.
Multiple bullet points begin with “Use” consecutively. Varying the sentence starters or rephrasing some items could enhance readability.
59-64: Review exclamation point usage.
The examples using exclamation points (e.g., “Congratulations on your success!” and “Happy birthday!”) are clear, but double-check that this tone matches your overall style guidelines and isn’t perceived as overly informal.🧰 Tools
🪛 LanguageTool
[style] ~64-~64: Using many exclamation marks might seem excessive (in this case: 4 exclamation marks for a text that’s 2474 characters long)
Context: ...ions on your success!" - "Happy birthday!" ## 8. Quotation Marks (" ") Use Quot...(EN_EXCESSIVE_EXCLAMATION)
markdown/docs/community/onboarding-guide/ambassador-guide.md (1)
29-30: Consider rephrasing for clarity.
In the Ambassador duties section, the phrase “Be in tune with AsyncAPI's mission and values” might be streamlined to “Align with AsyncAPI's mission and values” for brevity and clarity.🧰 Tools
🪛 LanguageTool
[style] ~29-~29: ‘in tune with’ might be wordy. Consider a shorter alternative.
Context: ...ole year. ### Ambassador duties - Be in tune with AsyncAPI's mission and values. - Always...(EN_WORDINESS_PREMIUM_IN_TUNE_WITH)
markdown/docs/community/styleguide/voice-and-tone.md (1)
53-58: Vary sentence structure in Style Tips.
Several bullet points start uniformly with “Use”. Consider varying the sentence beginnings or rephrasing some tips to increase readability and avoid repetition.markdown/docs/community/styleguide/formatting.md (2)
15-19: Enhance Bullet Point Style and Punctuation Consistency
Several bullet points begin with “Use,” which can feel repetitive. Consider varying the sentence structure for improved readability. Additionally, please:
- Capitalize “Markdown” on line 18 since it is a proper noun.
- Insert a comma after “Currently” on line 19 (i.e. “Currently, our documentation supports …”).
Suggested Diff:
- - Use an `>` in markdown to indicate the nature of the note or warning. + - Use an `>` in Markdown to indicate the nature of the note or warning.- - Use the following syntax to apply a style. Currently our documentation supports **Remember** `<Remember>`: + - Use the following syntax to apply a style. Currently, our documentation supports **Remember** `<Remember>`:🧰 Tools
🪛 LanguageTool
[style] ~16-~16: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ing to introduce the note or warning. - Use short paragraphs or bullet points to co...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[grammar] ~18-~18: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...uage simple and direct. - Use an>in markdown to indicate the nature of the note or w...(MARKDOWN_NNP)
[uncategorized] ~19-~19: A comma may be missing after the conjunctive/linking adverb ‘Currently’.
Context: ... the following syntax to apply a style. Currently our documentation supports Remember...(SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA)
94-94: Clarify Incomplete Instruction on Line 94
Line 94 appears to be incomplete or may be an extraneous line number without accompanying content. Please review and update or remove it as necessary.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
config/edit-page-config.json(1 hunks)markdown/docs/community/onboarding-guide/ambassador-guide.md(1 hunks)markdown/docs/community/onboarding-guide/maintainer-guide.md(1 hunks)markdown/docs/community/styleguide/formatting.md(1 hunks)markdown/docs/community/styleguide/punctuation.md(1 hunks)markdown/docs/community/styleguide/voice-and-tone.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/community/styleguide/voice-and-tone.md
[style] ~59-~59: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...mentation easier to read and digest. - Use headings, subheadings with proper hiera...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~61-~61: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... texts and make them more scannable. - Use examples and code snippets to illustrat...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~63-~63: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...epts and provide practical guidance. - Use contractions to make the language more ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
markdown/docs/community/onboarding-guide/ambassador-guide.md
[style] ~29-~29: ‘in tune with’ might be wordy. Consider a shorter alternative.
Context: ...ole year. ### Ambassador duties - Be in tune with AsyncAPI's mission and values. - Always...
(EN_WORDINESS_PREMIUM_IN_TUNE_WITH)
markdown/docs/community/styleguide/punctuation.md
[misspelling] ~27-~27: This word is normally spelled as one.
Context: ...e guides or personal preference. ## 3. Semi-colon (;) Use a semicolon to separate two in...
(EN_COMPOUNDS_SEMI_COLON)
[uncategorized] ~43-~43: Possible missing comma found.
Context: ...tes a sudden break or interruption in a sentence or provides emphasis. Some examples inc...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~46-~46: ‘brand new’ seems to be a compound adjective before a noun. Use a hyphen: “brand-new”.
Context: ...." - "She received an unexpected gift—a brand new car!" A hyphen (-) joins compound ...
(CA_BRAND_NEW)
[style] ~64-~64: Using many exclamation marks might seem excessive (in this case: 4 exclamation marks for a text that’s 2474 characters long)
Context: ...ions on your success!" - "Happy birthday!" ## 8. Quotation Marks (" ") Use Quot...
(EN_EXCESSIVE_EXCLAMATION)
markdown/docs/community/styleguide/formatting.md
[style] ~16-~16: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ing to introduce the note or warning. - Use short paragraphs or bullet points to co...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[grammar] ~18-~18: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...uage simple and direct. - Use an > in markdown to indicate the nature of the note or w...
(MARKDOWN_NNP)
[uncategorized] ~19-~19: A comma may be missing after the conjunctive/linking adverb ‘Currently’.
Context: ... the following syntax to apply a style. Currently our documentation supports Remember...
(SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA)
⏰ Context from checks skipped due to timeout of 180000ms (5)
- GitHub Check: Redirect rules - asyncapi-website
- GitHub Check: Header rules - asyncapi-website
- GitHub Check: Pages changed - asyncapi-website
- GitHub Check: Lighthouse CI
- GitHub Check: Test NodeJS PR - macos-13
🔇 Additional comments (21)
config/edit-page-config.json (1)
25-28: New community resource entry added.
A new entry for the "community/styleguide" resource has been included. Please verify that the"href"URL ("https://github.com/asyncapi/community/tree/master/docs/styleguide") is correct and aligns with the intended community assets.markdown/docs/community/styleguide/punctuation.md (1)
1-5: Metadata header is well-formed.
The frontmatter block—with the title, description, and weight—is correctly defined and follows the document standards.markdown/docs/community/onboarding-guide/ambassador-guide.md (2)
1-4: Metadata header is well-structured.
The title and weight parameters are clearly defined in the document’s frontmatter.
7-10: Introduction is clear and welcoming.
The opening lines set an inviting tone and effectively introduce the AsyncAPI Ambassador Program.markdown/docs/community/styleguide/voice-and-tone.md (2)
1-5: Metadata header is well-formed.
The frontmatter correctly provides the title, description, and weight in a clear and consistent manner.
7-20: Introduction and overview are clear.
The opening sections clearly explain the importance of voice and tone in the documentation, setting a consistent standard for communication.markdown/docs/community/onboarding-guide/maintainer-guide.md (3)
1-4: Metadata header is well-structured.
The frontmatter section with the title and weight is clear and consistent with project conventions.
7-10: Introduction is welcoming and informative.
The opening paragraphs effectively introduce the purpose of the Maintainer Guide and set the proper tone for the document.
11-25: Content is informative and detailed.
The guide clearly explains who an AsyncAPI Maintainer is and outlines their responsibilities. The detailed steps and expectations provide valuable direction for new maintainers.markdown/docs/community/styleguide/formatting.md (12)
1-6: YAML Front Matter is Properly Configured
The front matter correctly sets the title, description, and weight needed for this document.
7-10: Clear Introduction to Documentation Formatting
The explanation of formatting standards provides a solid foundation and is easy to understand.
11-14: Introduction to Notes and Warning Blocks is Informative
The heading and introductory sentence clearly explain the purpose of notes and warnings in the documentation.
20-31: Comprehensive Example for Custom Styling
The detailed instructions and examples for using the<Remember>tag are clear and helpful. Ensure that the code block formatting aligns with the overall site style.
32-43: Code Blocks Section is Well-Structured
The overview and instructions on using<CodeBlock>tags, including the example syntax, are clear and practical.
44-49: Output Example Demonstrates Expected Result
The output example effectively shows how the rendered code block should appear, aiding users in understanding the expected format.
50-53: Guidelines for Code Styling and Indentation are Clear
The recommendations for using code styles (e.g., using backticks for filenames and choosing consistent indentation) are concise and actionable.
54-63: Indentation Example is Effective
The code snippet clearly illustrates the proper indentation (using four spaces) for code examples, enhancing readability.
64-66: Inline Code and YAML Block Recommendations are Concise
The instructions for enclosing inline code with single backticks and the reminder to remove trailing spaces are well stated.
67-74: YAML Code Block Example is Informative
The example showing how to encapsulate YAML content within triple backticks is clear and serves as a good reference for proper formatting.
75-82: Displayed YAML Output Supports the Guidelines
The output example reinforces how the YAML code block should appear and complements the instructions provided above.
83-93: Spacing Guidelines are Well-Defined
The section on spacing, including recommendations for blank lines between paragraphs and after headings or lists, is thorough and helpful for readability.
akshatnema
deleted the
update-community-docs-2301b4607f3945b436aeae62f69a8f2dff636082
branch
Updated community documentation is available and this PR introduces update to community folder on the website
Summary by CodeRabbit
New Features
Documentation