docs(community): update latest community documentation #3820
Conversation
asyncapi-bot
requested review from
Mayaleeeee,
TRohit20,
akshatnema,
anshgoyalevil,
asyncapi-bot-eve,
derberg and
quetzalliwrites
as code owners
WalkthroughThis pull request updates the repository’s configuration and documentation by introducing several new resources. A new JSON entry is added to the configuration file for linking to a community style guide. Additionally, four new markdown documents are introduced: three onboarding guides (for ambassadors, maintainers, and voice & tone) and one formatting guide. These changes expand the available guides and standardize documentation and community resource references within the project. 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
|
❌ Deploy Preview for asyncapi-website failed.
|
asyncapi-bot
requested review from
Aahil13,
VaishnaviNandakumar,
ashmitjsg and
sambhavgupta0705
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #3820 +/- ##
=========================================
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 (7)
markdown/docs/community/onboarding-guide/maintainer-guide.md (1)
27-28: Punctuation Suggestion
There appears to be a potential missing comma after “answering questions” (e.g., “…not just by answering questions, but by teaching contributors…”) to improve readability. Please review and adjust as needed.🧰 Tools
🪛 LanguageTool
[uncategorized] ~28-~28: Possible missing comma found.
Context: ...r others not just by answering questions but by teaching contributors why coding s...(AI_HYDRA_LEO_MISSING_COMMA)
markdown/docs/community/onboarding-guide/ambassador-guide.md (1)
28-29: Language Refinement on Ambassador Duties
In the bullet item “Be in tune with AsyncAPI's mission and values,” consider using a more succinct phrasing (for example, “Be aligned with AsyncAPI's mission and values”) to improve clarity and polish the document’s tone.🧰 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/onboarding-guide/voice-and-tone.md (1)
52-63: Style Improvement: Varying Sentence Starters
In the “Style Tips” section, many bullet points begin with “Use.” Consider varying the sentence structure (e.g., “Apply,” “Employ,” or rephrase the sentence) to avoid repetition and improve readability.🧰 Tools
🪛 LanguageTool
[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/styleguide/formatting.md (4)
15-23: Markdown List Styling and Inline Code Spacing
Several points under “Notes and warning blocks” could be improved for consistency:
- Replace asterisks with dashes (
-) for unordered list items (to satisfy mdlint MD004).- Rephrase items to avoid starting every bullet with “Use” (e.g., for line 19, consider “Apply the following syntax…”).
- Additionally, in the inline code example at line 23, remove extraneous spaces so that it reads
<Remember>instead of` <Remember>.Suggested diff:
- * Surround the text you want to style with an opening <Remember> tag and a closing </Remember> tag. - * Note that the word 'Remember' does not need to be included within the tags, as it automatically provides the necessary styling. - * Use the following syntax to apply a style: + - Surround the text you want to style with an opening `<Remember>` tag and a closing `</Remember>` tag. + - Note that including the word 'Remember' inside the tags is unnecessary since the styling is applied automatically. + - Apply the following syntax to style text with `<Remember>` tags:Also, update the inline code on line 23 to remove extra spaces:
- ` <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)
🪛 markdownlint-cli2 (0.17.2)
20-20: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
21-21: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
22-22: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
23-23: Spaces inside code span elements
null(MD038, no-space-in-code)
38-42: Language Identifier for Fenced Code Blocks
For the fenced code block demonstrating the<CodeBlock>syntax (lines 38–42), add a language identifier (e.g., ```bash) immediately after the opening backticks to improve syntax highlighting and consistency.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
38-38: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
55-63: Specify Language for JavaScript Code Example
The fenced code block illustrating the JavaScript function (lines 55–63) would benefit from a language specifier (e.g., ```javascript) to enhance readability through proper syntax highlighting.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
55-55: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
67-73: Clarify YAML Code Block Example Syntax
The YAML code block example (lines 67–73) is a bit confusing due to the extra backticks and formatting. Consider reformatting this example to clearly separate the literal code snippet from the instructional text (for instance, by using a code fence without additional inline formatting).🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
67-67: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
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/onboarding-guide/voice-and-tone.md(1 hunks)markdown/docs/community/styleguide/formatting.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/community/onboarding-guide/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/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)
markdown/docs/community/onboarding-guide/maintainer-guide.md
[uncategorized] ~28-~28: Possible missing comma found.
Context: ...r others not just by answering questions but by teaching contributors why coding s...
(AI_HYDRA_LEO_MISSING_COMMA)
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)
🪛 markdownlint-cli2 (0.17.2)
markdown/docs/community/styleguide/formatting.md
20-20: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
21-21: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
22-22: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
23-23: Spaces inside code span elements
null
(MD038, no-space-in-code)
38-38: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
55-55: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
67-67: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
75-75: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
⏰ Context from checks skipped due to timeout of 180000ms (1)
- GitHub Check: Lighthouse CI
🔇 Additional comments (3)
config/edit-page-config.json (1)
23-29: JSON Configuration Entry for Community Styleguide
The new entry for the community styleguide is correctly added and follows the existing pattern. Please verify that the provided URL reflects the latest repository structure and desired user navigation.markdown/docs/community/onboarding-guide/maintainer-guide.md (1)
1-4: New Maintainer Onboarding Guide Document
The document is well structured and clearly outlines the roles and responsibilities expected of AsyncAPI maintainers.markdown/docs/community/onboarding-guide/voice-and-tone.md (1)
1-5: New Voice and Tone Document Added
This document clearly articulates the guidelines for voice, tone, and style, and the examples effectively illustrate the intended approach. Overall, the structure and content are solid.
akshatnema
deleted the
update-community-docs-f1f213e3f98903de7384a402701f640a4e986d6f
branch
Updated community documentation is available and this PR introduces update to community folder on the website
Summary by CodeRabbit