docs(community): update latest community documentation #3650
Conversation
asyncapi-bot
requested review from
quetzalliwrites,
asyncapi-bot-eve,
derberg,
akshatnema,
magicmatatjahu,
anshgoyalevil and
Mayaleeeee
as code owners
WalkthroughThis pull request expands the AsyncAPI documentation by adding a new JSON entry and multiple Markdown files. The JSON file now includes a link to the "community/onboarding-guide". New Markdown documents offer guidance on contributing to documentation, creating directories, community resources, onboarding checklists, pull request procedures, prerequisite knowledge, technical writer responsibilities, and tools setup. Changes
Suggested labels
Suggested reviewers
Poem
Tip 🌐 Web search-backed reviews and chat
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
Documentation and Community
|
asyncapi-bot
requested review from
BhaswatiRoy,
J0SAL,
TRohit20 and
VaishnaviNandakumar
✅ Deploy Preview for asyncapi-website ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #3650 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 20 20
Lines 732 732
=========================================
Hits 732 732 ☔ View full report in Codecov by Sentry. |
![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 (10)
markdown/docs/community/onboarding-guide/open-docs-pull-request.md (2)
1-4: Front Matter & Title Precision:
The front matter is properly declared. However, the title on line 2 ("Create new docs pull request") uses an article with a plural noun. Consider rephrasing to either “Create a new documentation pull request” or “Create new docs pull request” for clarity.
6-16: Detailed PR Process & Style Consideration:
The step-by-step process is clear and comprehensive. In addition, note the static analysis suggestion on line 14: “Tag an engineer or subject matter expert (SME)” could be refined to “Tag an engineer or subject‐matter expert (SME)” for improved clarity and consistency with style guidelines.🧰 Tools
🪛 LanguageTool
[grammar] ~6-~6: The plural noun “docs” cannot be used with the article “a”. Did you mean “a new doc” or “new docs”?
Context: ...ull request' weight : 90 --- ## Create a new docs pull request Create and submit a docs ...(A_NNS)
[grammar] ~14-~14: This term is normally spelled with a hyphen.
Context: ...ew your document. - Tag an engineer or subject matter expert (SME) to review the technical details. ...(SUBJECT_MATTER_HYPHEN)
markdown/docs/community/onboarding-guide/tools-and-setup.md (1)
16-16: Header Language Optimization:
Consider changing the header “Setup your AsyncAPI local environment” to “Set up your AsyncAPI local environment” to use the command verb form rather than the noun form, which improves clarity as an instruction.🧰 Tools
🪛 LanguageTool
[grammar] ~16-~16: This sentence should probably be started with a verb instead of the noun ‘Setup’. If not, consider inserting a comma for better clarity.
Context: ...scm.com), a version control system. ## Setup your AsyncAPI local environment 1. Fork...(SENT_START_NN_DT)
markdown/docs/community/onboarding-guide/docs-community.md (2)
6-6: Meeting Invitation WordingThe opening line ("Join OPEN docs community meetings via Zoom, a regular space for docs contributors to meet and help each other.") is clear; however, the phrasing “docs contributors” might be refined for clarity. Consider whether “documentation contributors” (or possibly “AsyncAPI docs contributors”) would improve readability.
[minor]🧰 Tools
🪛 LanguageTool
[grammar] ~6-~6: Nouns are not usually modified by plural nouns. Is it possible that you meant to use the singular or possessive form here?
Context: ... meetings via Zoom, a regular space for docs contributors to meet and help each othe...(PLURAL_MODIFIER)
15-22: Slack Workspace & Roadmap DetailsThe instructions for joining the AsyncAPI Slack workspace and the subsequent documentation roadmap are informative.
• For the table in lines 23–27, consider using Markdown-native list formatting (rather than embedded HTML<li>elements) for better consistency and portability across renderers.markdown/docs/community/onboarding-guide/prerequisite-knowledge.md (3)
6-10: Introduction & Diátaxis Framework OverviewThe introduction clearly outlines what prerequisite knowledge is expected from contributors. The explanation of the Diátaxis framework and the breakdown of content buckets are crisp and well presented.
• On line 16, consider a minor rephrasing such as “guides how to upgrade to a newer version of AsyncAPI” to improve clarity.
19-22: Markdown & Mermaid Diagram UsageThe sections on "Markdown syntax" and the use of Mermaid markdown syntax are informative. Note that “Markdown” is a proper noun; you might consider capitalizing it ("Mermaid Markdown syntax") for consistency.
🧰 Tools
🪛 LanguageTool
[grammar] ~22-~22: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ... Our diagrams are created with Mermaid markdown syntax thanks t...(MARKDOWN_NNP)
24-36: AsyncAPI Concepts, Formats, and ProtocolsThe detailed breakdown of AsyncAPI concepts, JSON/YAML formats, and protocols is comprehensive.
• There is a slight repetitive use of “AsyncAPI” in the protocols section—ensure that this repetition serves clarity rather than redundancy.
[minor]🧰 Tools
🪛 LanguageTool
[duplication] ~35-~35: Possible typo: you repeated a word.
Context: ...tate of EDAs.) ## Protocols used with AsyncAPI AsyncAPI supports several protocols, such as Kaf...(ENGLISH_WORD_REPEAT_RULE)
markdown/docs/community/onboarding-guide/technical-writer-contributor-responsibilities.md (1)
6-7: Collaboration DescriptionThe sentence on line 6 is informative. As noted by static analysis, consider hyphenating "Subject-Matter Experts (SME)" for consistency with common usage.
[minor]🧰 Tools
🪛 LanguageTool
[grammar] ~6-~6: This term is normally spelled with a hyphen.
Context: ...llaborate with other technical writers, Subject Matter Experts (SME), designers, engineers, and core m...(SUBJECT_MATTER_HYPHEN)
markdown/docs/community/onboarding-guide/create-new-docs-directories.md (1)
1-4: YAML Front Matter & Formatting ConsistencyThe YAML front matter is mostly correct; however, note the spacing around the colon in "title : 'Create new docs directories'"—for consistency with other files, remove the extra space (i.e. use "title:" instead).
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
config/edit-page-config.json(1 hunks)markdown/docs/community/onboarding-guide/_section.md(1 hunks)markdown/docs/community/onboarding-guide/contribute-to-docs.md(1 hunks)markdown/docs/community/onboarding-guide/create-new-docs-directories.md(1 hunks)markdown/docs/community/onboarding-guide/docs-community.md(1 hunks)markdown/docs/community/onboarding-guide/docs-onboarding-checklist.md(1 hunks)markdown/docs/community/onboarding-guide/index.md(1 hunks)markdown/docs/community/onboarding-guide/open-docs-pull-request.md(1 hunks)markdown/docs/community/onboarding-guide/prerequisite-knowledge.md(1 hunks)markdown/docs/community/onboarding-guide/technical-writer-contributor-responsibilities.md(1 hunks)markdown/docs/community/onboarding-guide/tools-and-setup.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- markdown/docs/community/onboarding-guide/_section.md
🧰 Additional context used
🪛 LanguageTool
markdown/docs/community/onboarding-guide/index.md
[grammar] ~15-~15: This term is normally spelled with a hyphen.
Context: ...audiences. * Connect with teammates and subject matter experts (SMEs). * Report documentation bugs via...
(SUBJECT_MATTER_HYPHEN)
markdown/docs/community/onboarding-guide/open-docs-pull-request.md
[grammar] ~6-~6: The plural noun “docs” cannot be used with the article “a”. Did you mean “a new doc” or “new docs”?
Context: ...ull request' weight : 90 --- ## Create a new docs pull request Create and submit a docs ...
(A_NNS)
[grammar] ~14-~14: This term is normally spelled with a hyphen.
Context: ...ew your document. - Tag an engineer or subject matter expert (SME) to review the technical details. ...
(SUBJECT_MATTER_HYPHEN)
markdown/docs/community/onboarding-guide/docs-community.md
[grammar] ~6-~6: Nouns are not usually modified by plural nouns. Is it possible that you meant to use the singular or possessive form here?
Context: ... meetings via Zoom, a regular space for docs contributors to meet and help each othe...
(PLURAL_MODIFIER)
markdown/docs/community/onboarding-guide/prerequisite-knowledge.md
[uncategorized] ~16-~16: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...e AsyncAPI specification. - Migration guides how to upgrade to a newer AsyncAPI vers...
(AI_HYDRA_LEO_APOSTROPHE_S_XS)
[grammar] ~22-~22: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ... Our diagrams are created with Mermaid markdown syntax thanks t...
(MARKDOWN_NNP)
[duplication] ~35-~35: Possible typo: you repeated a word.
Context: ...tate of EDAs.) ## Protocols used with AsyncAPI AsyncAPI supports several protocols, such as Kaf...
(ENGLISH_WORD_REPEAT_RULE)
markdown/docs/community/onboarding-guide/tools-and-setup.md
[grammar] ~16-~16: This sentence should probably be started with a verb instead of the noun ‘Setup’. If not, consider inserting a comma for better clarity.
Context: ...scm.com), a version control system. ## Setup your AsyncAPI local environment 1. Fork...
(SENT_START_NN_DT)
markdown/docs/community/onboarding-guide/create-new-docs-directories.md
[uncategorized] ~14-~14: Loose punctuation mark.
Context: ...for that directory. 2. _section.md: Used for reusable components or partial...
(UNLIKELY_OPENING_PUNCTUATION)
markdown/docs/community/onboarding-guide/technical-writer-contributor-responsibilities.md
[grammar] ~6-~6: This term is normally spelled with a hyphen.
Context: ...llaborate with other technical writers, Subject Matter Experts (SME), designers, engineers, and core m...
(SUBJECT_MATTER_HYPHEN)
⏰ Context from checks skipped due to timeout of 180000ms (3)
- GitHub Check: Automerge PR autoapproved by a bot
- GitHub Check: Test NodeJS PR - macos-13
- GitHub Check: Lighthouse CI
🔇 Additional comments (20)
markdown/docs/community/onboarding-guide/contribute-to-docs.md (2)
1-4: Front Matter & Metadata Validation:
The front matter is correctly structured with a title and weight. Ensure that the chosen weight (70) accurately reflects the desired ordering in the documentation navigation.
6-12: Content Clarity and Navigation:
The document clearly explains the three avenues for contributing to the docs. The step-by-step instructions and embedded links (e.g., to Slack and GitHub issues) enhance usability.config/edit-page-config.json (1)
21-25: New JSON Entry Consistency:
The new entry for"community/onboarding-guide"is added appropriately with the correct link. Please verify that the omission of a leading slash in the value (compared to some other entries) is intentional and consistent with the site's routing conventions.markdown/docs/community/onboarding-guide/index.md (3)
1-4: Front Matter Consistency:
The front matter is well-formatted with a clear title and weight assignment. Ensure the weight (10) correctly positions this page in the overall hierarchy.
5-10: Introduction & Guideline Reference:
The introductory section provides a concise overview of the technical writer onboarding guide. The in-text reference to the AsyncAPI contributing guidelines is very useful for new contributors.
11-19: List Formatting and Action Items:
The bullet list effectively outlines key goals for contributors. Consider a review to ensure consistency in tone and style with other AsyncAPI documents (e.g., using action verbs).🧰 Tools
🪛 LanguageTool
[grammar] ~15-~15: This term is normally spelled with a hyphen.
Context: ...audiences. * Connect with teammates and subject matter experts (SMEs). * Report documentation bugs via...(SUBJECT_MATTER_HYPHEN)
markdown/docs/community/onboarding-guide/tools-and-setup.md (3)
1-4: Front Matter Verification:
The front matter with title and weight is correctly formatted.
6-15: Comprehensive Tools & Prerequisites:
The list of required tools and setup prerequisites is detailed and clear. All necessary items (hardware, connectivity, GitHub account, editor, and Git) are mentioned.
17-47: Step-by-Step Instructions Clarity:
The setup instructions are well-structured, guiding contributors through forking, cloning, installing dependencies, and running the website locally. It may help to include a brief note explaining the<username>placeholder for newcomers to GitHub workflows.markdown/docs/community/onboarding-guide/docs-onboarding-checklist.md (3)
1-4: Front Matter & Metadata DefinitionThe YAML front matter is correctly defined with a title and weight. Ensure you maintain consistency in spacing and formatting across similar documents.
5-7: Checklist Heading & IntroductionThe header "## AsyncAPI docs onboarding checklist" and the introductory paragraph clearly outline the document’s purpose. The language is clear and sets the tone for the checklist.
9-22: Onboarding Tasks ListThe checklist items are well-structured and provide clear, step-by-step tasks for new contributors. Each bullet point includes useful links and instructions.
• Ensure that the links remain up to date as the documentation evolves.
• Consider running a link check as part of your CI process.markdown/docs/community/onboarding-guide/docs-community.md (3)
1-4: Front Matter & Document TitleThe YAML front matter with the title "AsyncAPI docs community" and the weight field is properly set up.
8-11: Calendar, Videos & Scheduling LinksThis segment lists actionable items such as adding the calendar and watching past meetings. The instructions are concise and user friendly.
12-14: Discussion Board InformationThe section on "Docs and education community discussions" succinctly informs users where to discuss docs-related issues and propose improvements.
markdown/docs/community/onboarding-guide/prerequisite-knowledge.md (1)
1-4: YAML Front Matter CheckThe front matter is properly declared with the title "Prerequisite knowledge" and a weight value. This is consistent with the other onboarding documents.
markdown/docs/community/onboarding-guide/technical-writer-contributor-responsibilities.md (2)
1-4: Document Metadata & TitleThe YAML front matter with the title "Technical writer contributor responsibilities" is clear and consistent.
8-14: Technical Writer Responsibilities ListThe bulleted list accurately outlines the responsibilities. The action items are clear and succinct. No issues noted.
markdown/docs/community/onboarding-guide/create-new-docs-directories.md (2)
6-15: Step-by-Step Instruction ClarityThe instructional steps (lines 6–15) are clear and provide a logical progression for creating new documentation directories. The detailed explanation for the two essential files (
index.mdand_section.md) is especially helpful.🧰 Tools
🪛 LanguageTool
[uncategorized] ~14-~14: Loose punctuation mark.
Context: ...for that directory. 2._section.md: Used for reusable components or partial...(UNLIKELY_OPENING_PUNCTUATION)
17-24: Mermaid Diagram for Visual AidThe Mermaid flowchart effectively illustrates the directory structure and file relationships. It enhances understanding and is a welcome visual addition.
asyncapi-bot
deleted the
update-community-docs-27db3e9ffada92a8d7251b591c8a46492ffbae7e
branch
Updated community documentation is available and this PR introduces update to community folder on the website
Summary by CodeRabbit
New Features
Documentation