docs(community): update latest community documentation #4286
Conversation
asyncapi-bot
requested review from
Mayaleeeee,
TRohit20,
akshatnema,
anshgoyalevil,
asyncapi-bot-eve,
derberg,
sambhavgupta0705 and
thulieblack
as code owners
WalkthroughThis change introduces a comprehensive reorganization and expansion of AsyncAPI's community documentation. It adds new sections and files covering onboarding, contribution guidelines, style guides, governance and policies, project vision and strategy, guides, mentorship programs, meetings and communication, and marketing. The update also modifies configuration files and removes obsolete section markers. Changes
Sequence Diagram(s)sequenceDiagram
participant Contributor
participant Docs Website
participant Community Repo
Contributor->>Docs Website: Navigates to Community Docs
Docs Website->>Community Repo: Loads structured sections (Onboarding, Guidelines, etc.)
Contributor->>Docs Website: Accesses guides, policies, onboarding, etc.
Docs Website->>Contributor: Displays organized content and navigation
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
Poem
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches🧪 Generate unit tests
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:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. 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
CBID2,
bandantonio,
devilkiller-ag and
vishvamsinh28
❌ Deploy Preview for asyncapi-website failed.
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #4286 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 22 22
Lines 778 778
Branches 144 144
=========================================
Hits 778 778 ☔ 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: 17
🔭 Outside diff range comments (1)
config/edit-page-config.json (1)
23-33: Two overlapping onboarding entries will cause unexpected edit-link resolutionBoth
"community/onboarding-guide"and"community/000-onboarding"match the same pages rendered under/community/000-onboarding/*.
BecausedetermineEditLink()returns the first match, the olderonboarding-guideentry will “win”, pointing to an obsolete location in thecommunityrepo. Recommend removing or moving the legacy entry to the end of the array.
🧹 Nitpick comments (106)
markdown/docs/community/community-glossary.md (1)
1-8: Placeholder doc should be hidden or clearly flagged as draftExposing an almost-empty page with a very high weight (
997) clutters the nav. Consider marking it as draft (or giving it a very low weight) until real content lands.weight: 997 +draft: true # hide from production nav until populatedmarkdown/docs/community/011-styleguide/numbers.md (1)
159-159: Missing newline at end of fileThe final line lacks a trailing newline, which is our usual convention for Markdown files. Consider adding it for consistency across the repo.
markdown/docs/community/010-contribution-guidelines/open-docs-pull-request.md (1)
9-13: Remove the curly apostrophe in “Docs’ PR”
The typographic apostrophe (’) can break some Markdown renderers and search indexing. Plain ASCII (Docs PR) is safer and consistent with the rest of the docs.- A Docs’ PR should solve one documentation problem. + A Docs PR should solve one documentation problem.markdown/docs/community/010-contribution-guidelines/prerequisite-knowledge.md (1)
11-15: Pluralise “Guide” → “Guides” to match classification terminology
The list refers to the Diátaxis buckets; everywhere else the bucket is named “Guides”.- `Guide` teaches troubleshooting and understanding AsyncAPI's capabilities at a high level. + `Guides` teach troubleshooting and understanding AsyncAPI's capabilities at a high level.markdown/docs/community/000-onboarding/where-to-contribute.md (1)
1-8: Mark placeholder as draft to avoid publishing half-done page
Settingdraft: truekeeps the page out of production builds until content is ready.--- title: Where to Contribute weight: 10 +draft: true ---markdown/docs/community/010-contribution-guidelines/technical-writer-contributor-responsibilities.md (1)
2-3: Verify weight & quoting consistency.• Raising
weightfrom 20 to 100 will push this page to the very bottom of the Contribution Guidelines menu. Confirm this is intentional.• Other docs usually wrap the
titlevalue in quotes. YAML accepts both, but aligning the style keeps diffs tidy.markdown/docs/community/060-meetings-and-communication/_section.md (1)
1-5: Minor style nit.Other
_section.mdfiles omit the trailing blank line after the closing---. For consistency you might remove line 5, but it’s purely cosmetic.markdown/docs/community/010-contribution-guidelines/tools-and-setup.md (1)
17-17: Minor wording tweak for clarity“Setup your AsyncAPI local environment” should be the verb form “Set up your AsyncAPI local environment”.
markdown/docs/community/070-marketing/social-media-communication-guidelines.md (1)
6-8: Placeholder needs a clearer status indicatorConsider adding a short TODO section or
draft: trueflag in front-matter so site visitors and search results recognise that the content is intentionally incomplete.markdown/docs/community/050-mentorship-program/_section.md (1)
2-4: Front-matter style inconsistencyOther new
_section.mdfiles omit quotes aroundtitle; using quotes here introduces stylistic divergence. Aligning formatting across section files keeps the front-matter uniform.markdown/docs/community/000-onboarding/how-to-contribute.md (1)
1-8: Document is just a placeholder – schedule completion or hide from sidebarReaders landing on empty pages perceive the docs as stale. Either:
- Add at least a high-level outline of the intended content, or
- Set
draft: true/ remove weight to keep it off navigation until ready.markdown/docs/community/000-onboarding/documentarian-onboarding-guide.md (1)
1-8: Placeholder page—apply same mitigation as other WIP onboarding docsConsider adding at least a bulleted outline (responsibilities, tooling, review flow) so early contributors have something actionable, or mark the page as draft until complete.
markdown/docs/community/030-project-vision-strategy-goals/ROADMAP.md (1)
1-8: Placeholder file committed—track follow-up
🚧 This document is under construction.Ensure there’s an open issue or task linked to completing the roadmap so the placeholder does not linger indefinitely.markdown/docs/community/index.md (1)
8-10: Remove trailing period to satisfy markdownlint MD026Heading ends with a period and is currently flagged by CI.
-## Community: Guidelines and resources around community. +## Community: Guidelines and resources around communitymarkdown/docs/community/010-contribution-guidelines/code-contributor-guide.md (2)
22-23: Style inconsistency in absolute vs relative URLsBullet #1 now uses a relative link (
git-workflow.md) while bullets #1 and #2 below keep absolute GitHub URLs. Consider switching to relative paths for consistency (mirrors practice across the new docs) or add a rationale in the doc if these two must remain absolute.
47-47: Nit: missing same-paragraph hyphen in “Every contribution matters, no matter how small.”Current text duplicates earlier encouragement; consider dropping this final sentence or moving it above the “Wait for Review & Merge” heading to avoid ending the doc with a floating paragraph.
markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2024-README.md (1)
14-14: Missing space: “18weeks”
18weeksrenders as a single word. Insert a space (18 weeks) for readability.markdown/docs/community/060-meetings-and-communication/index.md (1)
22-25: Cross-reference opportunityYou link to Slack etiquette in other docs; adding an inline link here (e.g., “See our Slack etiquette guidelines”) would help readers jump directly.
markdown/docs/community/010-contribution-guidelines/contribution-flow.md (2)
28-35: Internal link robustnessBoth occurrences of
git-workflow.mdrely on the file residing beside the current doc. If the file moves (e.g., to011-styleguide/or a shared folder) the links will break silently. Consider using absolute site-relative paths (/docs/community/010-contribution-guidelines/git-workflow) for long-term stability.
49-50: Link to Slack etiquette uses relative up-path traversal
../060-meetings-and-communication/slack-etiquette.mdworks today but is fragile if folder numbers change. A site-relative link (as suggested above) avoids future maintenance.markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2023-README.md (2)
6-8: Use an H2 for “Status” to avoid heading-level jumpThe file starts with a level-1 “Status” heading even though the front-matter title will already render an H1 on the site. This causes an MD001 violation and visually overshadows the actual document title.
Convert “# Status: Completed” to “## Status” (or a call-out) to keep a logical outline.
10-14: Minor copy-editing: tighten phrasing of the timeline“Project proposals applications” is redundant and the date ranges mix singular/plural forms. Consider:
• “Project proposal window: April 1 – June 6”
• “Mentee application window: June 6 – June 23”
• “Application review & admission: June 23 – July 7”This improves readability without altering meaning.
markdown/docs/community/010-contribution-guidelines/index.md (1)
16-19: Link bullet items to deeper guides for quicker navigationSince the sibling documents (
git-workflow.md,conventional-commits.md, etc.) already exist, turning these bullets into relative links will let newcomers jump straight to the details from this overview.markdown/docs/community/070-marketing/index.md (1)
6-13: Clarify audience and ownership of “Communication Guidelines”Stating who owns these standards (e.g., Marketing WG, Documentation WG) and which channels they cover (Twitter, LinkedIn, Slack, blog) will make this section actionable instead of purely descriptive.
markdown/docs/community/030-project-vision-strategy-goals/index.md (1)
13-18: Tie “Annual Planning” bullets to their source documentsThere are dedicated files (
2025_Community_Goals.md,2025_marketing_strategy.md). Adding inline links here will help readers trace the high-level statement to the respective concrete plans.markdown/docs/community/000-onboarding/docs-onboarding-checklist.md (1)
19-21: Consistent channel namesSlack references switch between
#13_docsand “#13_docs”. Prefer the backtick-style for both or none to keep style uniform.markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2022-README.md (1)
26-26: Convert the bare URL into a proper Markdown link
MD034flags the naked URL in the “Mentee?” column. Converting it to an actual Markdown link makes the table cleaner and keeps automated linters quiet.-<del>6</del> | <del>[Library for easier integration testing of code generators](https://github.com/asyncapi/generator/issues/752)</del> | [Generator](https://github.com/asyncapi/generator) | @derberg | 7 | https://github.com/asyncapi/community/discussions/376#discussioncomment-2898788 | +<del>6</del> | <del>[Library for easier integration testing of code generators](https://github.com/asyncapi/generator/issues/752)</del> | [Generator](https://github.com/asyncapi/generator) | @derberg | 7 | [discussion](https://github.com/asyncapi/community/discussions/376#discussioncomment-2898788) |markdown/docs/community/050-mentorship-program/summerofcode-README.md (3)
8-10: Use a level-2 heading instead of level-6Jumping from
#to######breaksMD001(heading-increment) and hurts readability. A level-2 heading is appropriate right after the H1.-###### Introduction +## Introduction
15-17: Pluralise and promote “Requirement” to H2Minor copy tweak and heading-level alignment.
-### Requirement +## Requirements
48-48: Tone down the exclamation markOne exclamation mark is enough; multiple can look unpolished.
-We appreciate your interest in choosing AsyncAPI for your Google Summer of Code project! +We appreciate your interest in choosing AsyncAPI for your Google Summer of Code project.markdown/docs/community/050-mentorship-program/index.md (2)
6-6: Tighten the opening sentence“Within the AsyncAPI Initiative to participation” is grammatically off. Consider:
-This section serves as your gateway to all mentorship opportunities within the AsyncAPI Initiative to participation in major open-source programs. +This section serves as your gateway to all mentorship opportunities within the AsyncAPI Initiative and to major open-source programs.
8-14: Replace bold text with proper headingsUsing emphasis in place of headings triggers
MD036and makes navigation harder.-**AsyncAPI Mentorship Programs** +## AsyncAPI Mentorship Programs ... -**External Programs** +## External Programsmarkdown/docs/community/050-mentorship-program/winterofcode-2023-README.md (2)
7-7: Fix typo and wrap bare URL-> Program participation annoucement can be found here https://github.com/orgs/asyncapi/discussions/556 +> Program participation announcement can be found [here](https://github.com/orgs/asyncapi/discussions/556)
17-18: Correct ordinal suffix- Project publication and Student registration starts: 23th January + Project publication and Student registration starts: 23rd Januarymarkdown/docs/community/050-mentorship-program/summerofcode-2024-README.md (1)
28-33: Add blank lines before and after the table
markdownlintMD058 warns because the table is not surrounded by blank lines.
Insert one empty line between the “## Accepted Project Ideas” heading and the first table row, and another after the final row. This also improves readability when viewed raw.markdown/docs/community/050-mentorship-program/summerofcode-mentors-guideline.md (1)
10-18: Adopt a consistently formal toneOpening with “Hey there!” makes the guideline noticeably more casual than the rest of the community docs. Consider re-phrasing the introduction to maintain the neutral, professional style used elsewhere (e.g. “Welcome to the Google Summer of Code (GSoC) mentor guideline.”).
markdown/docs/community/040-guides/keep-repository-settings-consistent.md (1)
34-37: Provide meaningful alt text for the screenshotThe current alt text is just “image”. Replace it with a short, descriptive sentence (e.g. “Screenshot showing how to trigger the global workflow in GitHub”). This benefits accessibility tools and search indexing.
markdown/docs/community/070-marketing/webinar_planning_template.md (1)
6-9: Start the document with a level-1 headingThe first visible heading is
### Basic Info, skipping levels 1 and 2 and triggering MD001.
Add a# AsyncAPI Webinar Planning Template(or similar) at the top so heading levels increment naturally.markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2023-project-ideas.md (2)
9-11: Fix heading level jump
### Ideas listjumps directly from# Projects ideasto level 3. Change it to## Ideas listto satisfy MD001 and keep a logical hierarchy.
32-32: Use a single spelling variant for “visualizer”Line 32 mixes British “visualiser” and US “visualizer”. Pick one variant (the project uses “visualizer” elsewhere) for consistency.
markdown/docs/community/050-mentorship-program/asyncapi-mentoring-initiatives.md (1)
8-9: Tighten wording in the introductionMinor style nit: “participates in a variety of mentoring programs” is wordy.
- The AsyncAPI Initiative participates in a variety of mentoring programs. + The AsyncAPI Initiative participates in multiple mentoring programs.markdown/docs/community/020-governance-and-policies/index.md (1)
10-13: Consider linking each bullet to the corresponding policy documentHyper-linking “AsyncAPI Charter”, “Technical Steering Committee”, etc., would let readers jump straight to the detailed files you added in this PR (e.g.,
CHARTER.md,TSC_MEMBERSHIP.md).
Makes navigation easier without waiting for the sidebar.markdown/docs/community/050-mentorship-program/summerofcode-2024-asyncapi-gsoc-ideas-page.md (3)
64-66: Sentence reads awkwardly – drop the duplicate article and add verb agreement
Ensure our conference website remains a dynamic and user-friendly for the upcoming 2024 AsyncAPI Conference.
→ “…remains dynamic and user-friendly…”.
Current wording mixes an article (‘a’) with an adjective and is grammatically off.
68-70: Mentor list is missing delimitersMentor handles are written without commas which renders as one long token:
[@acethecreator](…) [@mayaleeeee](…) [@thulieblack](…)Add commas (or
<br>separators) for readability and to avoid accidental Markdown link concatenation.
12-17: Minor consistency: emoji key vs. plain textBullet list mixes plain bullets and emoji bullets (🎯, 🛠️, etc.).
Sticking to one style gives a cleaner, machine-readable structure (helpful for future automated scraping of idea metadata).markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2022-project-ideas.md (1)
21-23: Stylistic: first-person “I think we” weakens the statementLine contains: “I think we should standardize…”.
Switch to active, community voice, e.g. “We should standardize…”.
Makes the guideline sound decisive and avoids hedge words flagged by LanguageTool.markdown/docs/community/020-governance-and-policies/TSC_VOTING_OVERVIEW.md (1)
6-7: Generated file notice is good – consider linking to the scriptThe comment warns against manual edits but does not point to the generator’s path.
Adding something like “(seescripts/community/update-tsc-voting-overview.js)” closes the loop for newcomers.markdown/docs/community/010-contribution-guidelines/contribute-blog-post.md (1)
10-12: Bare URLs – convert to Markdown links for consistencyConvert
https://squoosh.appto[Squoosh](https://squoosh.app)(and any other naked URLs) to comply with MD034 and maintain consistent link styling.markdown/docs/community/050-mentorship-program/summerofcode-application-template.md (2)
24-28: Parallel-construction mismatch in bullet listKeep verbs parallel:
“Provide a detailed description …”
(currently “Providing a detailed description …”)“Plan the project timeline …”
(current “How do you plan …” – acceptable, but consider starting with “Describe how you plan …” for symmetry)Helps reviewers scan each requirement quickly.
18-18: Missing space after parenthetical
Contact Number(include your country code)→Contact Number (include your country code)markdown/docs/community/050-mentorship-program/seasonofdocs-2023-project-ideas.md (2)
6-8: Avoid multiple top-level headings in one documentLines 6–8 introduce a second
#-level heading after the front-matter title, which breaks common Markdown style (one H1 per page). Consider downgrading the heading on line 8 to##(or lower) to keep a clear hierarchy.
26-28: Minor wording tweak for clarityThe phrase “specify thing that are common only for given protocol” (line 26) is awkward; “things that are specific to a given protocol” is smoother and grammatically correct.
markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2024-project-ideas.md (3)
6-9: Correct heading & typo“Projects ideas” (line 6) should read “Project ideas”.
Small polish but improves professionalism.
8-22: Duplicate section headingThe file contains two identical “### Ideas list” headings (lines 8 and 21). Promote the second one to a different title (e.g., “### Extended ideas list”) or merge the tables to avoid confusion.
18-19: Link formatting glitch
EDAVisualiser's[EDAVisualiser](line 18) is missing a space before the bracket, so the rendered link text will include the possessive “'s”. Insert a space to readEDAVisualiser’s [EDAVisualiser]….markdown/docs/community/010-contribution-guidelines/Become-maintainer-in-existing-project.md (1)
20-23: Long raw URL list can be noisyThe “good first issue” search link (line 20) is helpful but lengthy. Consider wrapping it in markdown reference style (
[good first issue label][gfi] …then[gfi]: https://…) to keep the bullet list readable.markdown/docs/community/070-marketing/webinar_series_initiative.md (1)
146-148: Remove trailing punctuation in headingMarkdown-lint MD026 reports the colon after “Disclaimer” (line 146) as trailing punctuation. Dropping the colon keeps the heading clean:
## Disclaimermarkdown/docs/community/011-styleguide/styling.md (2)
17-18: Replace bolded section titles with proper headings to satisfy MD036.Markdown-lint flags these four bold lines as “emphasis used instead of a heading”.
Turning them into#### Example(or similar) keeps the visual hierarchy clear and silences the linter.Also applies to: 37-38, 59-60, 94-95
84-90: Minor wording & consistency polish for the bulleted rules.Seven consecutive bullet points start with “Use …”. Consider varying phrasing or merging related points to avoid the LanguageTool repetition warning and improve readability.
markdown/docs/community/010-contribution-guidelines/git-workflow.md (1)
28-29: Front-matter: “Copy theDEFAULTbranch only” – clarify wording.GitHub UI currently says “Copy the
mainbranch only”. Using back-tickedDEFAULTcould mislead readers. Replacing with “Copy the default branch only (usuallymainormasterdepending on the repository)” would be clearer.markdown/docs/community/CODE_OF_CONDUCT_COMMITTEE.md (1)
10-11: Grammar fix in purpose sentence.“responds to investigates, and resolves” → “responds to, investigates, and resolves”.
markdown/docs/community/010-contribution-guidelines/identifying-good-first-issues.md (1)
70-77: Exclamation-point overuse.The closing paragraph ends with “So what are you waiting for? Go find your first quest, and let's build something awesome together!” — LanguageTool flags excessive enthusiasm. Consider toning it down to maintain a professional tone.
markdown/docs/community/COC-incident-resolution-procedures.md (2)
1-5: Windows-style CRLF line endings slipped in.Front-matter lines contain
\rcharacters (---\r). These sometimes trip markdown-lint and Git diff tools. Converting the file to LF endings keeps consistency with the rest of the docs.
233-238: “can not” → “cannot” and minor clarity tweaks.The phrase “can not” is flagged; replacing with “cannot” aligns with standard usage. While editing, consider trimming wordy phrases highlighted by LanguageTool (e.g., “taking into consideration”, “mutual agreement”) for conciseness.
markdown/docs/community/050-mentorship-program/summerofcode-2025-asyncapi-gsoc-ideas-page.md (5)
12-16: Unify technology names & capitalizationSeveral “Skills Required” lists mix casing and spellings (
Javascript/Typescript,Node js).
Please standardize across the document to the canonical forms “JavaScript/TypeScript” and “Node.js” for professionalism and searchability.Also applies to: 21-25
40-43: Consistent unit formatting
⏳ Length:fields alternate between “175 Hours”, “175 hours”, and “350 Hours”. Pick one style (e.g., “175 hours”) and apply it everywhere to avoid confusion.
75-79: Spelling – “TypeScript”Line 76 lists “Typescript”. The official spelling is “TypeScript” (capital ‘S’). Correct here and elsewhere.
81-86: Sentence clarityParagraph 72-74 (“Add E2E tests …”) uses “where” and a nested parenthesis that makes the sentence hard to parse. Consider rewriting to something simpler like
“…Add E2E tests for the website to thoroughly cover critical user-experience flows.”
84-88: Duplicate outcome textThe “Outcome” for project 9 repeats the text from project 8 and doesn’t mention dark-theme work. Adjust to describe the redesign & dark-mode deliverables.
markdown/docs/community/050-mentorship-program/seasonofdocs-2023-README.md (2)
48-56: Currency duplication
$350 dollarsrepeats the unit. Use either “$350” or “350 dollars” to avoid redundancy.
49-50: Tone – “want” / “completely”The sentence “we want to work with any TW … and we do not wish to have a bar …” is wordy. Dropping “want to” / “completely” tightens the prose without changing meaning.
markdown/docs/community/050-mentorship-program/summerofcode-2023-README.md (4)
60-64: Typo – “checkes”Line 62: “checkes” → “checks”.
52-53: Spelling – “TypeScript”Use the official capitalization for the language.
48-49: Singular/plural mismatch
175 Hourshould read175 hours.
146-147: WordinessPhrase “what is very important, that endpoint should be done in a similar way as” is cumbersome.
Consider “It is important that the endpoint is implemented similarly to the main CLI.”markdown/docs/community/050-mentorship-program/asyncapi-mentorship-README.md (1)
82-83: Mismatched quotation marks
Contributor(s)'’'contains two different apostrophes. Replace with a single standard apostrophe.markdown/docs/community/040-guides/add-new-asyncapi-tool-to-website.md (3)
64-77: Hard tabs in tableLines 64-76 use tab characters, triggering MD010. Replace tabs with spaces to keep table alignment and avoid lint warnings.
126-128: Spelling – “Moreover”Line 126: “Moreoever” → “Moreover”.
17-18: Grammar“create 2 or more
.asyncapi-toolfiles in same repository” →
“create two or more.asyncapi-toolfiles in the same repository” for smoother reading.markdown/docs/community/020-governance-and-policies/TSC_MEMBERSHIP.md (1)
71-75: Typo: “emojies” → “emojis”The plural of emoji is “emojis”. A small spelling fix will remove a visible error from the governance docs.
markdown/docs/community/011-styleguide/localization.md (1)
39-41: Grammar: missing “instead” in the example sentence
For example, of writing …→For example, instead of writing …Adds the missing word and reads naturally.
markdown/docs/community/020-governance-and-policies/AMBASSADOR_PROGRAM.md (1)
44-49: Section heading & wording polishThe heading “Ambassadors duties” is ungrammatical and should be “Ambassador duties” (or “Ambassadors’ duties”).
While updating, consider changing “Be in tune with” to “Align with” for conciseness.markdown/docs/community/000-onboarding/github-actions.md (3)
28-32: Remove the double spaces after list items to silence MD037.Lines 29-30 end with two trailing spaces, which markdownlint reports as “Spaces inside emphasis markers”.
Removing the extra spaces keeps the visual break in the rendered list while passing the linter.
47-56: Convert bare URLs to proper markdown links.The raw links in this block violate MD034 and break consistency with the rest of the page’s style.
Wrap them in angle brackets<…>or use[label](url)formatting.
80-90: Inline HTML<center>tags are deprecated in Markdown.Using
<center>works in GitHub-flavoured Markdown but is not guaranteed by every renderer and hurts accessibility.
Prefer CSS alignment via<div align="center">or leave alignment to the site’s stylesheet.markdown/docs/community/020-governance-and-policies/PROJECT_FUNDING.md (2)
45-49: Tighten wording and drop “on a regular basis”.The phrase is verbose and flagged by LanguageTool.
Example rewrite: “Assign employees to contribute regularly to AsyncAPI projects…”.
115-118: Replace “Feel free to” with a direct call to action.A more concise closing sentence improves professional tone, e.g.
“Contact us at [email protected] to discuss sponsorship or onboarding.”markdown/docs/community/030-project-vision-strategy-goals/2025_marketing_strategy.md (3)
91-97: Correct repeated misspelling “Mastadon” → “Mastodon”.The social-media platform name is misspelled in several places and trips LanguageTool.
85-90: Fix typos “neccessary” → “necessary” and “quater” → “quarter”.These appear in the newsletter paragraph and are flagged by LanguageTool.
120-122: Heading punctuation: remove trailing colon to satisfy MD026.
### Social Media Cross-Promotion:→### Social Media Cross-Promotionmarkdown/docs/community/020-governance-and-policies/introduction-of-changes-to-spec.md (2)
27-31: Grammar: plural agreement and clarity.“The contributors/maintainers reviews the proposed change” →
“Contributors/maintainers review the proposed change”Also consider splitting the long second sentence for readability.
69-70: Spelling: “preperation” → “preparation”.Minor typo in the Mermaid diagram description line.
markdown/docs/community/020-governance-and-policies/GOVERNANCE.md (3)
84-88: Fix heading-level jump (MD001).
#### Fran Mendezskips from level-2 (## Past directors) to level-4.
Change it to###to preserve a one-level increment.
16-18: Tighten wording to improve clarity.The phrase “prior to” is flagged by LanguageTool as wordy.
Consider replacing with “before”.
42-44: Simplify phrasing.“In the event that” → “If”; “prior to” → “before”.
Helps readability without altering meaning.markdown/docs/community/020-governance-and-policies/donating-projects.md (2)
22-25: Vary sentence starters to avoid repetition.Three consecutive items begin with “We …”, flagged by LanguageTool. Rephrase one or two for smoother flow.
32-46: Consider numbering list with ordered list syntax.Markdown numbers (
1. 2. 3.) will auto-increment and survive future insertions, reducing diff noise compared to hard-coded1-6in plain text.markdown/docs/community/011-styleguide/version-control.md (2)
57-59: Extra space in heading.
### When Submitting Changescontains double spaces. Remove one to avoid rendering artefacts.
93-95: Trim duplicated spacing.“patterns shown in existing” has two spaces before “in”.
markdown/docs/community/020-governance-and-policies/WORKING_GROUPS.md (1)
12-13: Concise wording.Replace “in a transparent manner” with “transparently” for brevity, as suggested by LanguageTool.
markdown/docs/community/050-mentorship-program/summerofcode-2021-README.md (1)
23-31: Use reference-style links for long URLs to improve readability.The paragraph contains two long inline links. Converting to reference style keeps the raw markdown cleaner.
markdown/docs/community/030-project-vision-strategy-goals/2025_Community_Goals.md (2)
9-15: Remove trailing colon in H2/H3 headingsMarkdown-lint (
MD026) flags headings that end with punctuation.
Consider dropping the colon from “Current Challenges:”, “Objectives to Address These Challenges:”, etc., to avoid noisy CI failures and keep heading style consistent across the docs.
42-61: Missingalttext in Mermaid block renderingAlthough Mermaid diagrams render as SVG in the final site, the raw markdown is still parsed by accessibility tooling.
Add a brief descriptive comment (%%) at the top of the Mermaid block so screen-reader users understand what the diagram conveys.markdown/docs/community/060-meetings-and-communication/MEETINGS_ORGANIZATION.md (1)
21-23: Unordered-list marker diverges from repo conventionThe AsyncAPI docs generally use
-for top-level unordered lists.
Replacing*with-keeps the markdown style uniform and silences markdown-lint ruleMD004.markdown/docs/community/010-contribution-guidelines/BOUNTY_PROGRAM.md (2)
16-20: Hyphenate compound adjective “open-source”In “individual open source maintainers”, “open-source” functions as a compound adjective modifying “maintainers”; hyphenating improves readability and aligns with style-guide conventions.
221-224: Prefer concise wording and avoid “prior to”Minor style point: “prior to” → “before” makes the sentence crisper and avoids
EN_WORDINESS_PREMIUM_PRIOR_TOwarnings. Same applies to earlier occurrences in the file.
markdown/docs/community/010-contribution-guidelines/contribute-blog-post.md
Show resolved
Hide resolved
markdown/docs/community/010-contribution-guidelines/identifying-good-first-issues.md
Show resolved
Hide resolved
| 5 | [Rewrite this template and NodeJS WS template](https://github.com/asyncapi/nodejs-template/issues/133) | [nodejs-template](https://github.com/asyncapi/nodejs-template) | [Lukasz Gornicki](https://github.com/derberg) | [Nodejs-template](https://github.com/asyncapi/nodejs-template) and also [nodejs-ws-template](https://github.com/asyncapi/nodejs-ws-template) are written with old [Nunjucks templating engine](https://github.com/asyncapi/generator/blob/master/docs/authoring.md#nunjucks). We need to rewrite them to [React templating engile](https://github.com/asyncapi/generator/blob/master/docs/authoring.md#react-1) that should become the default and only engine in the future. | ||
| 6 | [Simulator Desktop Application](https://github.com/asyncapi/community/issues/691) | [simulator](https://github.com/asyncapi/simulator) | [Nektarios Fifes](https://github.com/NektariosFifes) |To turn the CLI application into a complete desktop application that aims to visualize an AsyncAPI file and allow the user to generate traffic interactively. |
There was a problem hiding this comment.
Correct typo “engile” → “engine”
In the description for idea 5, “React templating engile” should read “engine”.
🤖 Prompt for AI Agents
In
markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2023-project-ideas.md
around lines 17 to 18, fix the typo "engile" by changing it to "engine" in the
description for idea 5 to correct the spelling of "React templating engine".
markdown/docs/community/050-mentorship-program/asyncapi-mentorship-README.md
Show resolved
Hide resolved
markdown/docs/community/050-mentorship-program/seasonofdocs-2022-README.md
Show resolved
Hide resolved
markdown/docs/community/060-meetings-and-communication/MEETINGS_ORGANIZATION.md
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 13
🔭 Outside diff range comments (2)
markdown/docs/community/011-styleguide/_section.md (1)
1-4: Missing closing front-matter delimiter breaks Hugo parsingOnly the opening
---delimiter is present. Without the closing delimiter (---) Hugo treats the whole file—including subsequent files in the same folder—as front-matter, causing build failures or silent mis-ordering in the sidebar.
Add the closing delimiter on a new line afterweight: 4.config/edit-page-config.json (1)
23-41: Duplicate style-guide entries
community/styleguide(lines 23-29) andcommunity/011-styleguide
(lines 39-41) point to the same content hierarchy. Keeping both will surface
two “Edit this page” links that diverge only by path, which can confuse users
and tests. Recommend keeping a single canonical entry.
🧹 Nitpick comments (103)
markdown/docs/community/community-glossary.md (2)
1-4: Add metadata to improve discoverability and guard against premature publicationThe front-matter is minimal. Consider adding a short
description:for SEO/search-listing purposes and, if the page is not supposed to render until content is ready, includedraft: true(or the equivalent in your docs generator) to hide it from navigation.
6-8: Double-check whether an unfinished placeholder should be publishedThe “🚧 under construction” notice is useful for contributors but may look unpolished to end-users if the page goes live. Confirm that the site build treats this page appropriately (hidden, flagged, or excluded from production) until full content lands.
markdown/docs/community/000-onboarding/where-to-contribute.md (1)
1-8: Placeholder acknowledged—remember to track completionDocument is clearly marked as WIP. Ensure there’s an open issue or project task so this doesn’t ship unnoticed in production docs.
markdown/docs/community/070-marketing/social-media-communication-guidelines.md (1)
6-8: Add a clear “TODO” to signal work-in-progressThe placeholder text is helpful, but adding an explicit
TODO:(or similar) flag makes unfinished pages easier to surface in automated checks and searches.markdown/docs/community/011-styleguide/index.md (1)
2-3: Minor consistency checkOther section headers use single-quoted titles (
'Title'). Here the quotes were removed. Not blocking, but consider aligning for stylistic consistency across the new community docs.markdown/docs/community/011-styleguide/grammar.md (1)
75-76: Minor list-indent inconsistencyThe two reference bullets have two leading spaces, unlike the rest of the document’s top-level bullets. While harmless in Markdown, aligning indentation keeps the raw file tidy.
markdown/docs/community/010-contribution-guidelines/open-docs-pull-request.md (1)
9-15: Wording tweak improves clarityBullet “After implementing all the feedback you requested” reads awkwardly. Consider “After addressing all requested feedback”.
markdown/docs/community/000-onboarding/how-to-contribute.md (1)
6-8: Prefer an admonition block for “under construction” noticesUsing a standard admonition (e.g.
:::warning/> **Note:**) keeps the docs style consistent and lets tooling or future lint rules recognise the placeholder more easily than a plain paragraph with emojis.markdown/docs/community/030-project-vision-strategy-goals/_section.md (1)
1-4: Missing trailing newline at EOFMost markdown files in the repo end with a newline to avoid diff-only changes later. Add one here for consistency.
markdown/docs/community/index.md (1)
8-8: Remove trailing period to satisfy MD026
markdownlintflags headings that end with punctuation.
Change:
## Community: Guidelines and resources around community.
to
## Community: Guidelines and resources around communitymarkdown/docs/community/000-onboarding/documentarian-onboarding-guide.md (1)
6-8: Same admonition suggestion as for “How to Contribute”Consider wrapping the placeholder in an admonition block for consistency with other docs sections.
markdown/docs/community/010-contribution-guidelines/mentoring-maintainers.md (1)
99-101: Prefer relative URLs for internal docs
The first two resources use absolute URLs to asyncapi.com, whereas the third is an external site. Converting the AsyncAPI link to a relative path keeps the build portable across preview environments and avoids hard-coding the domain.markdown/docs/community/010-contribution-guidelines/code-contributor-guide.md (1)
21-23: Mixed absolute vs. relative paths
The Code of Conduct and Contributing links still point to the GitHub repo. If equivalent docs now exist in the website itself, prefer relative links to avoid external hop and keep users on the site.markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2024-README.md (2)
6-6: Heading should start at H2, not H1The page title provided in the front-matter is rendered as the implicit H1.
Starting the content with# Statustherefore skips a level and violates MD001.
Change# Status:→## Status:(and adjust subsequent headings if needed).
14-14: Missing space: “18weeks” → “18 weeks”Minor readability issue – insert a space between the number and the unit.
markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2023-README.md (2)
6-6: Heading level off by oneSame issue as in the 2024 file – start with
## Status:instead of#.
14-14: Add space: “Six months”
Six monthsshould include a space for consistency (Six months).markdown/docs/community/060-meetings-and-communication/index.md (1)
6-6: Opening sentence hard to parseThe first sentence is 40 + words and mixes several ideas. Consider splitting it
into two shorter sentences for clarity.markdown/docs/community/050-mentorship-program/index.md (1)
6-6: Sentence reads awkwardlyConsider inserting a comma after “Initiative” and removing “to” before
“participation” for smoother flow.markdown/docs/community/010-contribution-guidelines/contribution-flow.md (1)
14-21: Two quasi-identical “Before …” sections – consider mergingThe document contains “Before You Start Contributing” and immediately afterwards “Before Making a Contribution”. The bullet-point content overlaps and may confuse first-time readers.
A single consolidated pre-work section will be clearer and reduce maintenance overhead.markdown/docs/community/050-mentorship-program/winterofcode-2023-README.md (3)
6-8: Spelling & link caption nit
annoucement→announcement.
Tiny typo in a high-visibility sentence; worth correcting.
16-19: Incorrect ordinal – “23th” should be “23rd”Fixing this avoids distracting readers and keeps timelines professional.
30-38: Table alignment & accessibility
- The header row is missing the trailing pipe (
|) in the Markdown table; depending on the renderer this may mis-align columns.- Use full GitHub handle links (
[@AceTheCreator](https://github.com/AceTheCreator)) instead of bare@mentions to render consistently.markdown/docs/community/010-contribution-guidelines/index.md (1)
10-37: Consider converting plain bullets into linksReaders landing here expect quick navigation. Turning each bullet into a hyperlink to the corresponding guide (where available) will improve UX and SEO.
markdown/docs/community/040-guides/keep-repository-settings-consistent.md (1)
32-38: Screenshot alt-text missingThe embedded image has no descriptive alt-text, reducing accessibility and SEO. Add a brief description, e.g.
.markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2023-project-ideas.md (3)
6-10: Heading level skips & wording nit
# Projects ideasuses a plural noun incorrectly (“Projects”) and the next visible heading jumps straight to### Ideas list, skipping an##level. This breaks MD001 heading-increment lint and slightly hurts readability.
17-18: Typo: “engile”Line 17 contains “templating engile”. Replace with “templating engine”.
32-33: Inconsistent spelling: visualiser / visualizerLine 32 mixes British “visualiser” with the predominantly-used “visualizer” elsewhere in AsyncAPI docs. Pick one spelling for consistency.
markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2022-README.md (1)
25-27: Bare URL inside table cellRow 26 exposes a raw URL, triggering MD034. Consider converting it to a normal markdown link or descriptive text to avoid lint warnings and keep the table readable.
markdown/docs/community/020-governance-and-policies/index.md (2)
10-18: Add internal links for quicker navigationEach bullet references a concrete document that is already part of this folder (
CHARTER.md,GOVERNANCE.md,TSC_MEMBERSHIP.md,TSC_VOTING_OVERVIEW.md,WORKING_GROUPS.md,voting.md). Turning the bullet text into relative links will let readers jump straight to the detailed material and keeps parity with other community pages that already do this.
26-34: Consistency in list phrasingMost list items start with a noun phrase (“Project funding opportunities”, “Guidelines for donating”…), but line 34 uses “Ambassador Program details” (noun) while line 35 switches to a gerund (“Recognition systems”). Aligning the grammatical form keeps the overview crisp.
markdown/docs/community/050-mentorship-program/asyncapi-mentoring-initiatives.md (3)
6-9: Trim soft marketing language“The AsyncAPI Initiative participates in a variety of mentoring programs.” ‑> “The AsyncAPI Initiative participates in several mentoring programs.” reduces wording without losing meaning and avoids the cliché “a variety of”.
17-20: Capitalize “Slack” and clarify channel nameCapital “Slack” is preferred, and explicitly naming the
#mentorship(or current) channel helps newcomers find it without guessing.
34-46: Totals column readabilityThe “Total (per year)” value is only present on the first row for each year. Consider moving totals to a separate summary row or repeating the value in every row so screen-reader users do not miss the number.
markdown/docs/community/050-mentorship-program/seasonofdocs-2022-README.md (2)
14-16: Avoid bare URLs – wrap in angle brackets
https://twitter.com/QuetzalliWritesandhttps://twitter.com/derberqare bare URLs that trigger MD034. Wrapping them in<…>or using Markdown link syntax prevents linter noise.
26-28: Use an en-dash for date ranges“September - October” should use an en-dash (“September – October”) according to the style guide already adopted in other docs.
markdown/docs/community/050-mentorship-program/summerofcode-mentors-guideline.md (2)
1-4: Title says “Guideline” but content reads as multiple guidelinesConsider renaming to “GSoC Mentors’ Guidelines” (plural, possessive) to match the breadth of the document and typical AsyncAPI section naming.
16-19: Bullets are overly long and hard to scanEach bullet currently spans several sentences. Splitting into sub-bullets (e.g., separate “Provide guidance”, “Encourage collaboration”, “Set expectations”…) will improve readability and make it easier for mentors to tick items off mentally.
markdown/docs/community/050-mentorship-program/summerofcode-README.md (1)
15-21: Section title should be plural“### Requirement” → “### Requirements” for grammatical correctness and consistency with other docs (“Key Responsibilities”, “First Steps”).
markdown/docs/community/030-project-vision-strategy-goals/index.md (1)
10-23: Link to referenced sub-documents so readers don’t have to hunt for themThe bullets mention the roadmap and other planning documents but don’t actually link to them. Adding relative links (once the files exist) makes navigation smoother and keeps the user inside the docs website.
markdown/docs/community/000-onboarding/upholding-code-of-conduct.md (1)
45-50: Convert the plain e-mail/URLs to Markdown links to comply with MD034
[email protected]and the GitHub URL are rendered as bare links, which markdown-lint flags. Wrapping them in[text](mailto:[email protected])/[link](…)keeps the page free of linter noise.markdown/docs/community/010-contribution-guidelines/recognize-contributors.md (1)
30-45: Fix table pipes & list-marker style to silence MD055 / MD004The contributors table is missing the trailing pipe and the unordered list at lines 48-49 uses
*while the rest of the file uses-. Harmonising these two cosmetic issues will clear the markdown-lint warnings.markdown/docs/community/050-mentorship-program/summerofcode-2024-asyncapi-gsoc-ideas-page.md (1)
63-70: Grammar nit: sentence reads awkwardlyLine 64 currently reads “Ensure our conference website remains a dynamic and user-friendly for the upcoming 2024 AsyncAPI Conference.”
Dropping the article a (“remains dynamic and user-friendly”) makes the sentence scan correctly.markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2024-project-ideas.md (1)
6-14: Minor polish: title casing and blank lines around the first table
- Heading “Projects ideas” should be “Project Ideas”.
- Add a blank line before and after the table (MD058) to avoid linter noise.
These tweaks keep headings consistent across the community docs and keep CI clean.markdown/docs/community/050-mentorship-program/asyncapi-mentorship-2022-project-ideas.md (2)
6-6: Fix plural → singular in section header
# Projects ideasshould read# Project ideasfor correct grammar.
21-30: Tighten wording & tone in several idea descriptionsLanguage-tool flags phrases like “a lot of”, “do a great job”, “issue in difficulty”, and “I think we should…”.
Replacing them with concise, assertive wording will strengthen the copy and keep the style consistent with the rest of the docs.markdown/docs/community/010-contribution-guidelines/contribute-blog-post.md (2)
21-26: Fix unordered-list indentation and wrap bare URLMarkdown-lint flags incorrect 3-space indentation on the nested list and the bare URL in line 23.
Indent the three sub-bullets with two spaces and wrap the Squoosh link in angle brackets or markdown link syntax to silence MD007 and MD034.
14-17: Numbered list uses repeated “1.”While GitHub renders this fine, using sequential numbers (1, 2, 3) avoids confusion in raw files and satisfies markdown-lint defaults.
markdown/docs/community/050-mentorship-program/summerofcode-application-template.md (3)
8-9: Remove repetition of “impress”Sentence currently reads “…crafting impressive proposals that will impress us.”
Dropping the second “impress” keeps the intro crisp.
16-18: Minor formatting – missing space
Contact Number(include your country code)→Contact Number (include your country code)
34-37: Inconsistent bullet indentation triggers MD007Line 37 is indented three spaces, others zero. Align all bullets to the same indentation depth.
markdown/docs/community/050-mentorship-program/seasonofdocs-2023-project-ideas.md (1)
32-35: Trim double space and fix minor wording
create a learning experiencehas a double space; also consider replacing “We’d love to create a learning experience that is useful, fun, and interactive!” with a more direct statement to match the professional tone used elsewhere.markdown/docs/community/040-guides/index.md (1)
10-12: Convert bullets to navigable linksReaders will likely expect each bullet to take them directly to the detailed guide you just added in the same PR (
add-new-asyncapi-tool-to-website.md,keep-repository-settings-consistent.md, …). Converting these list items into relative links will improve discoverability and reduce friction.Also applies to: 15-17, 21-23
markdown/docs/community/060-meetings-and-communication/slack-etiquette.md (1)
22-30: Consider ending guideline bullets with periods for consistencyMost bullets are short sentences but omit terminal punctuation, while others (e.g., lines 28-30) include it. A consistent style—either all with or all without periods—will make the list look cleaner and align with the new style-guide section you introduced.
markdown/docs/community/050-mentorship-program/summerofcode-2023-README.md (2)
61-65: Fix typos and missing period• “checkes” → “checks”
• “etc” → “etc.” (the style guide calls for the period)
These small errors break the professional tone and will trip markdown-lint (MD065, LanguageTool).
142-146: Streamline wordy sentenceThe phrase “Also, what is very important, that endpoint should be done in a similar way as…” is hard to parse and flagged by LanguageTool. Something like:
“Also, the endpoint should mirror the CLI’s behaviour …”
conveys the idea more directly.markdown/docs/community/011-styleguide/styling.md (2)
48-52: Minor punctuation & spacing“rulesets(already defined above)” is missing a space: “rulesets (already defined above)”. Keeps the document readable and consistent with the formal writing tone established elsewhere.
84-91: Bullet repetition flagged by linter
markdownlintnotices three consecutive bullets starting with “Use”. While not critical, varying phrasing (“Place”, “End each …”) would silence the linter and read less monotonously.markdown/docs/community/CODE_OF_CONDUCT_COMMITTEE.md (1)
10-11: Grammar fix: missing comma after “responds to”The sentence should read: “responds to, investigates, and resolves…”. Current wording is awkward and may confuse readers.
markdown/docs/community/020-governance-and-policies/TSC_MEMBERSHIP.md (3)
28-29: Indentation breaks nested-list renderingThe explanatory paragraph starting with “Depending on the project's size…” is indented by only two spaces. In most Markdown engines (including MDX used on asyncapi.com) this is not enough to keep the text inside the previous bullet and it will be rendered as a new top-level paragraph, visually disconnecting it from the list item it elaborates.
Increase the indent to four spaces or convert the note into a sub-bullet for consistent list formatting.
56-59: Wordiness + idiomThe phrase “Always behave with respect to the AsyncAPI Code of Conduct” is awkward. A more direct formulation such as “Always comply with the AsyncAPI Code of Conduct” is shorter and clearer.
71-74: Misspelling and plural form of “emoji”“emojies” ➜ “emoji” or “emojis”. Using the correct plural avoids distracting readers and keeps the document professional.
markdown/docs/community/020-governance-and-policies/donating-projects.md (2)
14-17: Long, hard-to-parse sentenceThe sentence beginning “Donating your project to an open-source organization like AsyncAPI can be exciting, hence why we need to ensure…” is lengthy and contains multiple clauses. Consider splitting it into two sentences for readability (e.g., end after “exciting.” and start a new sentence with “Therefore, we must ensure…”).
22-25: Repetitive sentence openingsBoth bullet points start with “We …”. Varying the sentence openings or removing the leading pronoun will make the list less repetitive and more concise.
markdown/docs/community/010-contribution-guidelines/identifying-good-first-issues.md (1)
70-76: Tone & punctuationThe guide ends with multiple exclamation marks and very informal language (“So what are you waiting for? … let’s build something awesome together!”). Reducing punctuation and slightly formalising the closing sentence will align the tone with the rest of the documentation.
Also applies to: 79-80
markdown/docs/community/COC-incident-resolution-procedures.md (4)
100-104: Tighten phrase to avoid wordiness in notification paragraph
The sub-clause “taking into consideration …” is verbose. Re-phrasing to “while considering risks of retaliation, evidence tampering, or witness intimidation” conveys the same meaning more succinctly.
110-114: Streamline consecutive “If …” sentences and replace “mutual agreement”
Three sentences in this block start with “If”, which reads repetitive. Consider merging or varying sentence openings. Also, “mutual agreement” can be shortened to “agreement” without loss of meaning.
196-198: Remove the intensifier “very”
Using “very small number” adds little value and weakens the statement. “a small number of people” is clearer.
237-238: Use “cannot” instead of “can not”
The standard form is “cannot”. Keeping wording consistent helps readability.markdown/docs/community/070-marketing/webinar_series_initiative.md (2)
8-13: Minor wording refinement for stronger opening
Replacing “deeper insights” with “practical insights” avoids the over-used “deeper” adjective and emphasises applicability.
35-40: Bullet prefix repetition
Each bullet begins with “For …”. Dropping the repeated prefix or converting to a table will reduce redundancy and improve scannability.markdown/docs/community/050-mentorship-program/summerofcode-2025-asyncapi-gsoc-ideas-page.md (3)
49-50: Add hyphen in compound adjective
“Open-source contribution” should be hyphenated when used as a compound adjective.
67-68: Consistent technology names
Use “TypeScript” and “Node.js” (official capitalisation and dot) instead of “Typescript” / “Node js” to keep terminology uniform across the document.
84-86: Outcome text duplicated from previous idea
The outcome for project 9 matches project 8 and doesn’t mention the redesign or dark-theme deliverable. Updating the sentence will prevent confusion.markdown/docs/community/011-styleguide/localization.md (2)
39-41: Correct introductory phrase in date-time example
“Of writing” appears to be a typo. “Instead of writing03/04/2024 8:00 AM, use …” reads correctly.
46-47: Clarify numeric example wording
The phrase “one thousand and fifty hundredths” is unusual. Consider “one thousand point five zero” or simply omit the verbal description.markdown/docs/community/020-governance-and-policies/introduction-of-changes-to-spec.md (5)
9-11: Grammar: capitalisation and comma placement
The sentence beginning “Some changes, however, are ‘substantial,’ We ask …” should use a lowercase “we” and a semicolon or period after “substantial” to avoid a run-on.
20-22: Subject-verb agreement
“The spec changes lifecycle consist of 2 parts” → “consists of two parts”.
25-29: Plural/verb agreement
“contributors/maintainers reviews” → “contributors/maintainers review”.
69-69: Spelling
“preperation” → “preparation”.
52-54: Tone
The phrase “and the world of open source won again” feels informal for a governance document. Consider removing or rephrasing.markdown/docs/community/050-mentorship-program/seasonofdocs-2023-README.md (2)
53-55: Replace hard-tabs with spaces for Markdown lint complianceLines 53 and 55 contain literal tab characters (
\t). They trigger MD010 and render inconsistently across editors. Replace them with two or four spaces to keep bullet-point alignment predictable.
59-59: Avoid redundant currency notationThe phrase “$350 dollars” repeats the currency symbol. Use either “$350” or “350 dollars” (preferred by LanguageTool) to stay concise and grammatically correct.
markdown/docs/community/050-mentorship-program/asyncapi-mentorship-README.md (1)
82-83: Fix malformed possessive apostrophe
Contributor(s)'’'contains a stray right-single-quote after the apostrophe. Drop the extra character so it readsContributor(s)’or rewrite the sentence to avoid the awkward construction altogether.markdown/docs/community/020-governance-and-policies/voting.md (1)
16-19: Rephrase to reduce repeated “only” and improve flowThe two consecutive sentences start with “Voting must only” and “Voting automation works only”. Consider merging or rewording to prevent repetition and make the guidance crisper, e.g.:
“Voting takes place exclusively in the community repository, and automation functions only on GitHub issues or pull-requests.”
markdown/docs/community/000-onboarding/github-actions.md (2)
58-60: Unordered list style deviates from project conventionMD004 flags the asterisk bullets here. Other lists in the doc—and the wider docs set—use dash (
-) style. Switching to dashes keeps lint quiet and maintains visual consistency.
95-103: Promote bold labels to real headingsThe bold “Opt-in” / “Opt-out” labels act as section headers but are just paragraphs with emphasis. Converting them to
###(or appropriate level) headings improves navigation, auto-generated TOCs, and satisfies MD036.markdown/docs/community/020-governance-and-policies/AMBASSADOR_PROGRAM.md (2)
27-43: Clarify renewal timeline and clean up wording in the requirements section• The statement on annual verification is ambiguous:
“we will check if you qualify again after the 5th of May 2022” → should reference the following year (2023).
• Examples 1–3 begin with three consecutive sentences starting with “If …”; consider re-phrasing or using a table to improve readability.
• Minor grammar issues (“propel 1 initiative” / “get new sponsors”) make the requirements harder to parse.Recommend tightening the language and explicitly stating the evaluation window (e.g., “on the anniversary of your acceptance each year”).
63-67: Replace bare URLs and remove blank line inside blockquoteMarkdown-lint flags MD034 & MD028 here:
-> **The process of obtaining the GitHub ID number** -<https://api.github.com/users/derberg> +> **How to obtain your GitHub ID** +> 1. Open `https://api.github.com/users/<your-github-handle>` in a browser. +> 2. Copy the value of the `id` field from the returned JSON.Removing the blank line keeps the blockquote intact and converting the raw URL to an inline code segment silences MD034 while retaining clarity.
markdown/docs/community/010-contribution-guidelines/recognizing-contributors-and-appointing-new-maintainers.md (1)
42-49: Unify unordered-list markers for consistencyEarlier lists use dashes (
-) while the two items at lines 48-49 switch to asterisks, triggering markdown-lint MD004. Pick one style (dashes are used elsewhere in the repo) for all bullet lists.-* **Community Mindset**: … -* **Technical Alignment**: … +- **Community Mindset**: … +- **Technical Alignment**: …markdown/docs/community/011-styleguide/version-control.md (1)
57-61: Fix heading typo and restore spacingExtra double-space after “Submitting” breaks some markdown renderers and link anchors.
-### When Submitting Changes +### When Submitting Changesmarkdown/docs/community/050-mentorship-program/summerofcode-2021-README.md (1)
21-31: Tighten wording in project descriptionSentence “A library that as the input gets two AsyncAPI documents and shows changes between them.” is hard to parse. Consider:
“A library that takes two AsyncAPI documents as input and outputs the JSON pointers for all differences.”
Clearer wording improves comprehension and professionalism of archival content.
markdown/docs/community/020-governance-and-policies/PROJECT_FUNDING.md (1)
35-41: Raw HTML<center>tag can be droppedMarkdown rendering engines already center block-level images by default (or through CSS). Keeping the legacy
<center>element adds noise and may break styling in some themes.
Recommend removing the tag and relying on CSS classes if alignment tweaking is needed.markdown/docs/community/020-governance-and-policies/GOVERNANCE.md (1)
84-88: Heading level skips from H2 → H4
#### Fran Mendezis an H4 directly under the H2 “Past directors”. Markdown-lint flags this as MD001.
Change to### Fran Mendez(and the same for Łukasz) to keep a logical H3 level.markdown/docs/community/030-project-vision-strategy-goals/2025_marketing_strategy.md (1)
143-150: Heading markup is offset
### Metrics to Trackis indented with a leading space, violating MD023 (heading-start-left) and breaking anchor generation. Left-align the hash symbols.markdown/docs/community/020-governance-and-policies/WORKING_GROUPS.md (1)
12-13: “in a transparent manner” → avoid fillerConsider the simpler “work transparently” for brevity.
markdown/docs/community/010-contribution-guidelines/BOUNTY_PROGRAM.md (1)
253-259: Heading level jump (H5 under H2) triggers MD001The “Sources” list starts with
##### …even though the previous heading is H2. Use###or restructure to maintain a one-level increment.markdown/docs/community/030-project-vision-strategy-goals/2025_Community_Goals.md (3)
36-38: Fix missing space after period for readabilityThere is no whitespace after the period that precedes “Once”, resulting in “...build upon.Once”.
Add a single space to avoid a run-on token.-...we can record and build upon.Once we have some onboarding available, +...we can record and build upon. Once we have some onboarding available,
78-88: Normalize unordered-list indentation (MD007 violation)Items are indented by four spaces instead of the repository-standard two, tripping markdown-lint and rendering inconsistently.
- - Rebrand the name AACoT. - - Revise the conference prospectus. - - Continue the API Standards Booth, ensuring it is bigger, better, and properly planned. - - Revamp the current conference website following the rebranding. - - Get conference sponsors and work to convince the AsyncAPI Initiative to become a platinum sponsor. - - Plan conferences outside of Europe (the majority should be outside Europe/Schengen). - - Lastly, we need to start planning as soon as possible! + - Rebrand the name AACoT. + - Revise the conference prospectus. + - Continue the API Standards Booth, ensuring it is bigger, better, and properly planned. + - Revamp the current conference website following the rebranding. + - Get conference sponsors and work to convince the AsyncAPI Initiative to become a platinum sponsor. + - Plan conferences outside of Europe (the majority should be outside Europe/Schengen). + - Lastly, we need to start planning as soon as possible!
24-33: Consider splitting very long sentence for clarityBullet #3 contains a 70-word sentence beginning with “We are looking for ways…”.
Breaking it into two sentences will increase readability, especially for non-native speakers.markdown/docs/community/060-meetings-and-communication/MEETINGS_ORGANIZATION.md (3)
21-23: Use consistent bullet marker (-instead of*)The repository’s docs generally use
-for unordered lists. Switching here prevents markdown-lint MD004 warnings.-* `Regular` meetings: regular meetings with a dedicated area of interest and individual brand (Examples: `Community Meeting` or `Thinking Out Loud`) -* `Ad Hoc` meetings: meetings for topics that do not match any **regular** meetings and should be organized separately. Every official AsyncAPI Zoom licensed user should have the right to schedule it. +- `Regular` meetings: regular meetings with a dedicated area of interest and individual brand (examples: `Community Meeting` or `Thinking Out Loud`) +- `Ad Hoc` meetings: meetings for topics that do not match any **regular** meetings and should be organized separately. Every official AsyncAPI Zoom-licensed user should have the right to schedule it.
52-58: Add alt text to images (MD045 violation)All inline
<img>tags lackaltattributes, which hurts accessibility and SEO.
Provide concise descriptions.- <img src="../../assets/meetings/restream1.png" width="50%" /> + <img src="../../assets/meetings/restream1.png" alt="Restream home – select setup for OBS, Zoom etc." width="50%" />(Apply similar alt text to the remaining images.)
198-221: Convert bare URLs to reference links to silence MD034 and improve readabilityMarkdown-lint flags these naked links; wrapping them with link text keeps the doc tidy.
markdown/docs/community/020-governance-and-policies/donating-projects.md
Show resolved
Hide resolved
markdown/docs/community/040-guides/keep-repository-settings-consistent.md
Show resolved
Hide resolved
markdown/docs/community/050-mentorship-program/seasonofdocs-2022-README.md
Show resolved
Hide resolved
markdown/docs/community/060-meetings-and-communication/MEETINGS_ORGANIZATION.md
Show resolved
Hide resolved
|
@thulieblack, do we still need this PR? |
Updated community documentation is available and this PR introduces update to community folder on the website
Summary by CodeRabbit
New Features
Improvements
Removals