Skip to content

Conversation

@asyncapi-bot
Copy link
Contributor

@asyncapi-bot asyncapi-bot commented Mar 6, 2025

Updated community documentation is available and this PR introduces update to community folder on the website

Summary by CodeRabbit

  • New Features
    • Expanded community resources with an additional link providing access to a comprehensive style guide.
  • Documentation
    • Introduced new onboarding guides for AsyncAPI Ambassadors and Maintainers.
    • Added style guides covering documentation formatting, inclusive language, punctuation, and voice & tone.

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Mar 6, 2025

Walkthrough

This pull request adds a new JSON entry to the configuration file and introduces several new markdown documents. The configuration file now includes a link to a community style guide. Additionally, new onboarding guides for AsyncAPI Ambassadors and Maintainers are provided, covering roles, responsibilities, and procedures. Four new style guide documents have also been added, detailing formatting, inclusive language, punctuation, and voice and tone for documentation.

Changes

File(s) Change Summary
config/edit-page-config.json Added a new JSON object entry for "community/styleguide" with its associated GitHub URL.
markdown/docs/community/onboarding-guide/*.md Added two new onboarding guides: one for AsyncAPI Ambassadors and one for AsyncAPI Maintainers outlining roles, responsibilities, and workflows.
markdown/docs/community/styleguide/*.md Added four new style guide documents covering formatting, inclusive language, punctuation, and voice and tone for documentation preparation.

Possibly related PRs

Suggested labels

autoapproved, autoupdate

Suggested reviewers

  • derberg
  • quetzalliwrites
  • magicmatatjahu
  • VaishnaviNandakumar
  • devilkiller-ag
  • J0SAL
  • akshatnema
  • BhaswatiRoy
  • sambhavgupta0705
  • anshgoyalevil
  • Mayaleeeee
  • TRohit20
  • asyncapi-bot-eve

Poem

I'm a rabbit hopping with glee,
New guides and configs set code free!
JSON links and markdown pages abound,
In every file, new treasures are found.
With a whisker twitch and a joyful nod,
I celebrate this update—oh, how grand it is, by God!
Hop on, my friend, let’s code and applaud!


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.

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Generate unit testing code for this file.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai generate unit testing code for this file.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and generate unit testing code.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

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)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

@netlify
Copy link

netlify bot commented Mar 6, 2025

Deploy Preview for asyncapi-website failed.

Name Link
🔨 Latest commit 4955d44
🔍 Latest deploy log https://app.netlify.com/sites/asyncapi-website/deploys/67ce33964515a10008058809

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (11)
markdown/docs/community/styleguide/punctuation.md (2)

27-27: Nitpick: Standardize "semicolon" terminology
The heading “## 3. Semi-colon (;)” uses a hyphenated form. It is more common to use “Semicolon” as a single word.

-## 3. Semi-colon (;)
+## 3. Semicolon (;)
🧰 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)


46-46: Refactor Suggestion: Compound adjective formatting
In the example “She received an unexpected gift—a brand new car!”, consider hyphenating “brand-new” to clarify that it functions as a compound adjective.

-"She received an unexpected gift—a brand new car!"
+"She received an unexpected gift—a brand-new car!"
🧰 Tools
🪛 LanguageTool

[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)

markdown/docs/community/onboarding-guide/ambassador-guide.md (1)

29-29: Suggestion: Rephrase repetitive wording
Instead of “Be in tune with AsyncAPI's mission and values,” consider a concise alternative such as “Align with AsyncAPI's mission and values” to reduce wordiness.

- - Be in tune with AsyncAPI's mission and values.
+ - Align with AsyncAPI's mission and values.
🧰 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)

52-62: Style Improvement: Diversify bullet point phrasing
Several bullet points in the “Style Tips” section start with the same word “Use,” which can feel repetitive. Consider varying the language to improve readability.

- - Use "you" to address the reader directly, e.g., "You will be using the Eclipse Mosquitto broker."
- - Use "we" to refer to the documentation authors, e.g., "We recommend using the latest version of the AsyncAPI specification."
- - Use short sentences and paragraphs to make the documentation easier to read and digest.
- - Use headings, subheadings with proper hierarchy, and bullet points to break up texts and make them more scannable.
- - Use examples and code snippets to illustrate concepts and provide practical guidance.
- - Use contractions to make the language more conversational, e.g., "You've now added a new section called servers in your AsyncAPI document."
+ - Address the reader directly, e.g., "You will be using the Eclipse Mosquitto broker."
+ - Refer to the documentation authors with “we”, for example, "We recommend using the latest version of the AsyncAPI specification."
+ - Keep sentences short and paragraphs concise to enhance readability.
+ - Incorporate headings, subheadings, and bullet points to effectively break up the content.
+ - Illustrate concepts with relevant examples and code snippets.
+ - Consider employing contractions to maintain a conversational tone, e.g., "You've now added a new section called servers in your AsyncAPI document."
🧰 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)

markdown/docs/community/styleguide/formatting.md (3)

15-19: Style Suggestion: Improve bullet list variety and punctuation
In the “Notes and warning blocks” section, the bullet list items all begin with “Use,” which can be made more engaging by varying the phrasing. Additionally, in line 19, consider inserting a comma after “Currently” for better readability.

-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)


20-23: Markdown Lint: Unordered List Style
The sublist under the “Notes and warning blocks” section uses asterisks. For consistency with our markdown guidelines, please use dashes (-) for unordered list markers.

-* 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 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:
🧰 Tools
🪛 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)


55-63: Enhancement: Specify language for fenced code block
The code block demonstrating proper indentation does not specify a language, which can affect syntax highlighting in some renderers. Consider adding a language identifier (e.g., javascript).

-```
+```javascript
 function myFunction() {
-    if (condition) {
-        console.log("Condition is true.");
-    } else {
-        console.log("Condition is false.");
-    }
-}
-```
+    if (condition) {
+        console.log("Condition is true.");
+    } else {
+        console.log("Condition is false.");
+    }
+}
+```

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.17.2)</summary>

55-55: Fenced code blocks should have a language specified
null

(MD040, fenced-code-language)

</details>

</details>

</blockquote></details>
<details>
<summary>markdown/docs/community/onboarding-guide/maintainer-guide.md (1)</summary><blockquote>

`27-29`: **Sentence Punctuation Enhancement**  
In the sentence “You’ll mentor others not just by answering questions but by teaching contributors *why* coding standards matter or *how* to structure a feature,” consider adding a comma after “others” to improve readability.

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 LanguageTool</summary>

[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)

</details>

</details>

</blockquote></details>
<details>
<summary>markdown/docs/community/styleguide/inclusive-language.md (3)</summary><blockquote>

`12-20`: **Section: Culturally Inclusive Language – Grammar & Consistency Enhancements**  
The “Culturally inclusive language” section provides valuable guidance along with specific examples. However, consider these revisions for improved grammatical consistency:
  
```diff
- - Terms like "gypsy" is considered derogatory in Romani community, "eskimo" is considered offensive in artic community.
- - Terms like "tipping point" is considered offensive in African American cultures.
+ - Terms like "gypsy" are considered derogatory in the Romani community, and "eskimo" is considered offensive in the Arctic community.
+ - Terms like "tipping point" are considered offensive in African American cultures.

These changes ensure proper subject–verb agreement and the inclusion of necessary articles.

🧰 Tools
🪛 LanguageTool

[style] ~18-~18: When writing in more formal contexts, you might want to consider a different expression.
Context: ...l languages instead of English. - “It’s a piece of cake” is commonly used in the USA, and non-U...

(PIECE_OF_CAKE)


[uncategorized] ~19-~19: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...to it as intended. - Terms like "gypsy" is considered derogatory in Romani communi...

(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)


[uncategorized] ~19-~19: You might be missing the article “the” here.
Context: ...ike "gypsy" is considered derogatory in Romani community, "eskimo" is considered offen...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)


[uncategorized] ~19-~19: You might be missing the article “the” here.
Context: ...ty, "eskimo" is considered offensive in artic community. - Terms like "tipping point"...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)


[uncategorized] ~20-~20: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...community. - Terms like "tipping point" is considered offensive in African America...

(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)


35-41: Section: Accessibility and Disability – Clarity & Consistency
The discussion on accessibility and disability is comprehensive. For consistency, consider using lowercase for descriptors such as “ableism” (instead of “Ableism”) and verify that the examples maintain a uniform tone and structure.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~39-~39: Possible missing comma found.
Context: ...discrimination against individuals with disabilities or the assumption that people with dis...

(AI_HYDRA_LEO_MISSING_COMMA)


71-80: Section: Knowledge Level Assumption-Free Language – Enhancement Suggestion
While the guidelines are clear, the bullet point “Linking complex topics that most of our audience won’t understand” could benefit from clarification. Consider rephrasing or expanding on how to manage complex topics without assuming prior knowledge.

🧰 Tools
🪛 LanguageTool

[style] ~77-~77: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... with” instead of “fixing the navbar is very easy”. - Linking complex topics that most of...

(EN_WEAK_ADJECTIVE)

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d6a213a and 8a10d31.

📒 Files selected for processing (7)
  • 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/inclusive-language.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/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)

markdown/docs/community/styleguide/inclusive-language.md

[style] ~18-~18: When writing in more formal contexts, you might want to consider a different expression.
Context: ...l languages instead of English. - “It’s a piece of cake” is commonly used in the USA, and non-U...

(PIECE_OF_CAKE)


[uncategorized] ~19-~19: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...to it as intended. - Terms like "gypsy" is considered derogatory in Romani communi...

(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)


[uncategorized] ~19-~19: You might be missing the article “the” here.
Context: ...ike "gypsy" is considered derogatory in Romani community, "eskimo" is considered offen...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)


[uncategorized] ~19-~19: You might be missing the article “the” here.
Context: ...ty, "eskimo" is considered offensive in artic community. - Terms like "tipping point"...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)


[uncategorized] ~20-~20: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...community. - Terms like "tipping point" is considered offensive in African America...

(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)


[misspelling] ~22-~22: This word is normally spelled with a hyphen.
Context: ...ve in African American cultures. ## 2. Gender neutral language Some phrases and words target...

(EN_COMPOUNDS_GENDER_NEUTRAL)


[uncategorized] ~24-~24: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...entation. Using only male pronouns also make women in technology feel excluded or ov...

(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)


[style] ~30-~30: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nstead of “Chairman” or “Chairwoman”. - Using "people", "guests" or "folks" instead o...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~31-~31: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s" instead of "ladies and gentlemen". - Using "Mx" or "Ms" instead of using "Mr" or "...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~32-~32: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... "Ms" instead of using "Mr" or "Mrs". - Using "humankind" instead of "mankind". - Avo...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[uncategorized] ~39-~39: Possible missing comma found.
Context: ...discrimination against individuals with disabilities or the assumption that people with dis...

(AI_HYDRA_LEO_MISSING_COMMA)


[style] ~46-~46: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...bility" instead of "Disabled people". - Using "Wheelchair Users" instead of "Wheelcha...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[style] ~47-~47: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...Users" instead of "Wheelchair bound". - Using "People experiencing homelessness" inst...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)


[uncategorized] ~65-~65: Possible missing comma found.
Context: ... include - - Avoid mentioning the exact age like “60 years” old. - Using "experienc...

(AI_HYDRA_LEO_MISSING_COMMA)


[style] ~77-~77: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... with” instead of “fixing the navbar is very easy”. - Linking complex topics that most of...

(EN_WEAK_ADJECTIVE)

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)


[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)

🪛 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 (2)
  • GitHub Check: Automerge PR autoapproved by a bot
  • GitHub Check: Lighthouse CI
🔇 Additional comments (14)
config/edit-page-config.json (1)

23-29: Configuration Update – New Community Resource Entries
The new entries for community/onboarding-guide and community/styleguide have been added correctly, following the existing pattern.

markdown/docs/community/onboarding-guide/maintainer-guide.md (9)

1-4: Front Matter & Metadata Validation
The YAML front matter is correctly formatted with clear title and metadata. Double-check that the assigned weight (100) positions this guide appropriately among the other onboarding documents.


7-11: Introduction Clarity
The introductory section warmly welcomes readers and succinctly states the guide’s purpose. The content is engaging and sets a positive tone for new maintainers.


13-26: Maintainer Definition & Responsibilities
The section “Who is an AsyncAPI Maintainer?” clearly lays out the role and responsibilities using a bullet list. This helps new contributors understand the scope of the maintainer role immediately.


32-32: Section Heading – Steps to Becoming a Maintainer
The heading is clear and provides a logical transition into the step-by-step process.


36-41: Step 1: Pick an Issue
The guidelines for selecting an issue are descriptive and include useful links to actual GitHub queries and Slack channels. This actionable advice will help onboard new contributors effectively.


42-46: Additional Live Stream Guidance
The recommendation to participate in live streams is a great touch. Please verify that the live stream link and channel references remain current.


47-57: Step 2: Open a PR Process
The detailed instructions covering forking, making changes, and engaging in discussions ensure clarity in the PR process. Including references like the AsyncAPI Git Workflow Guide further bolsters the guide’s utility.


59-66: Step 3: PR Merge Process
The merge process is concisely explained. It could be beneficial to emphasize that all automated checks must pass prior to merging to avoid potential issues.


67-71: Step 4: Invitation to Maintainership
The final step effectively celebrates the achievement with a clear explanation and a celebratory icon. This positive framing reinforces the path toward deeper community involvement.

markdown/docs/community/styleguide/inclusive-language.md (4)

1-5: Front Matter & Metadata Validation
The YAML front matter provides a concise title, description, and weight for the guide. This metadata efficiently introduces the document and aids in its organization within the community docs.


7-11: Introduction: Inclusive Language
The introduction effectively sets the context by emphasizing the importance of inclusive language. The message is clear and aligns well with the overall community values.


51-60: Section: Slang-Free Language
The guidelines to avoid slang are clear and the examples provided are beneficial. Double-check that all bullet points follow similar formatting for the best reader experience.


61-69: Section: Ageism-Free Language
The recommendations in this section are straightforward and easy to follow. Ensure that the examples provided are current and reflect modern best practices for inclusive language.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~65-~65: Possible missing comma found.
Context: ... include - - Avoid mentioning the exact age like “60 years” old. - Using "experienc...

(AI_HYDRA_LEO_MISSING_COMMA)

Comment on lines +22 to +26
## 2. Gender neutral language

Some phrases and words target men or men/women specifically, resulting in other gender groups feeling left out while reading our documentation. Using only male pronouns also make women in technology feel excluded or overlooked.
Similarly, we should also try to include nonbinary groups of people in our writing.
Some examples of gender-neutral language are -
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Section: Gender Neutral Language – Verb Agreement Correction
In the sentence, “Using only male pronouns also make women in technology feel excluded or overlooked,” replace “make” with “makes” to maintain subject-verb agreement.

- Using only male pronouns also make women in technology feel excluded or overlooked.
+ Using only male pronouns also makes women in technology feel excluded or overlooked.

This correction will enhance grammatical accuracy.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## 2. Gender neutral language
Some phrases and words target men or men/women specifically, resulting in other gender groups feeling left out while reading our documentation. Using only male pronouns also make women in technology feel excluded or overlooked.
Similarly, we should also try to include nonbinary groups of people in our writing.
Some examples of gender-neutral language are -
## 2. Gender neutral language
Some phrases and words target men or men/women specifically, resulting in other gender groups feeling left out while reading our documentation. Using only male pronouns also makes women in technology feel excluded or overlooked.
Similarly, we should also try to include nonbinary groups of people in our writing.
Some examples of gender-neutral language are -
🧰 Tools
🪛 LanguageTool

[misspelling] ~22-~22: This word is normally spelled with a hyphen.
Context: ...ve in African American cultures. ## 2. Gender neutral language Some phrases and words target...

(EN_COMPOUNDS_GENDER_NEUTRAL)


[uncategorized] ~24-~24: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...entation. Using only male pronouns also make women in technology feel excluded or ov...

(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)

@codecov
Copy link

codecov bot commented Mar 7, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (8612ccc) to head (4955d44).

Additional details and impacted files
@@            Coverage Diff            @@
##            master     #3822   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           21        21           
  Lines          667       667           
  Branches       113       113           
=========================================
  Hits           667       667           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@akshatnema
Copy link
Member

@thulieblack, kindly add the _section.md and index.md files to the respective folders in the doc. Otherwise we will not be able to add these docs in the website.

@thulieblack
Copy link
Member

Thanks I totally forgot

@akshatnema akshatnema deleted the update-community-docs-8eafd4996e04d982d7553680ebcad607effe9afa branch August 3, 2025 18:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants