-
-
Notifications
You must be signed in to change notification settings - Fork 137
docs: reorganize documents in the community repo #1833
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
docs: reorganize documents in the community repo #1833
Conversation
57bbceb
to
4b64d50
Compare
You have some conflicts 😁 |
/ptal |
@derberg @quetzalliwrites @thulieblack Please take a look at this PR. Thanks! 👋 |
4b64d50
to
7e95323
Compare
Important Review skippedReview was skipped as selected files did not have any reviewable changes. 💤 Files selected but had no reviewable changes (2)
You can disable this status message by setting the WalkthroughThis pull request reorganizes documentation within the community repository by updating outdated links, adding new guides, and removing obsolete files. Several documents now reference updated file paths to match the new directory structure. New onboarding and contribution guides have been introduced, while redundant tweet files and a duplicated Git workflow guide have been removed. These changes aim to improve navigation, consistency, and overall accessibility of the community documents. Changes
Assessment against linked issues
Poem
🪧 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
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (10)
docs/070-marketing/social-media-communication-guidelines.md (1)
3-3
: Friendly Status Message
The message on line 3 is user-friendly and encourages patience. Consider adding a note or link to a roadmap/timeline if available, so users know when to expect the final version.docs/community-glossary.md (1)
1-3
: Document Under Construction Notice
The document clearly indicates that it is under construction, which is appropriate for an early draft. As development progresses, consider adding a brief outline or roadmap that highlights planned sections to better guide readers.GOVERNANCE.md (1)
18-25
: Consistent Charter Link Update and Language Refinement
The charter link has been updated to./docs/020-governance-and-policies/CHARTER.md
consistently in the duties list, which aligns with the new documentation structure. Additionally, in the bullet starting on line 25, consider revising “has no power” to “have no power” to ensure proper subject-verb agreement.🧰 Tools
🪛 LanguageTool
[style] ~20-~20: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ive community for everyone to thrive. * Make sure AsyncAPI is economically viable, i...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~25-~25: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...rs, etc. * Must be a servant leader and has no power other than the specified in th...(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)
docs/060-meetings-and-communication/MEETINGS_ORGANIZATION.md (1)
47-125
: Add Alt Text to Image Elements
Multiple image elements throughout the document (e.g., lines 47, 51, 58, 62, 66, 70, 74, 84, 88, 92, 94, 96, 100, 104, 110, 117, 121, and 125) lack descriptivealt
text. To improve accessibility and adhere to Markdown best practices (MD045), please add appropriate alternative text to each image. For example, update-<img src="../../assets/meetings/restream1.png" width="50%"> +<img src="../../assets/meetings/restream1.png" alt="Illustration of Restream setup" width="50%">🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
47-47: Images should have alternate text (alt text)
null(MD045, no-alt-text)
51-51: Images should have alternate text (alt text)
null(MD045, no-alt-text)
58-58: Images should have alternate text (alt text)
null(MD045, no-alt-text)
62-62: Images should have alternate text (alt text)
null(MD045, no-alt-text)
66-66: Images should have alternate text (alt text)
null(MD045, no-alt-text)
70-70: Images should have alternate text (alt text)
null(MD045, no-alt-text)
74-74: Images should have alternate text (alt text)
null(MD045, no-alt-text)
84-84: Images should have alternate text (alt text)
null(MD045, no-alt-text)
88-88: Images should have alternate text (alt text)
null(MD045, no-alt-text)
92-92: Images should have alternate text (alt text)
null(MD045, no-alt-text)
94-94: Images should have alternate text (alt text)
null(MD045, no-alt-text)
96-96: Images should have alternate text (alt text)
null(MD045, no-alt-text)
100-100: Images should have alternate text (alt text)
null(MD045, no-alt-text)
104-104: Images should have alternate text (alt text)
null(MD045, no-alt-text)
110-110: Images should have alternate text (alt text)
null(MD045, no-alt-text)
117-117: Images should have alternate text (alt text)
null(MD045, no-alt-text)
121-121: Images should have alternate text (alt text)
null(MD045, no-alt-text)
125-125: Images should have alternate text (alt text)
null(MD045, no-alt-text)
docs/CODE_OF_CONDUCT_COMMITTEE.md (1)
28-29
: Decision-Making Section Wording
The revised text outlining the decision-making process is comprehensive. However, consider shortening the phrase “a majority of non-conflicted members” to enhance clarity, as suggested by static analysis.🧰 Tools
🪛 LanguageTool
[style] ~28-~28: ‘a majority of’ might be wordy. Consider a shorter alternative.
Context: ...manent action shall require approval of a majority of non-conflicted members of the CoC Commi...(EN_WORDINESS_PREMIUM_A_MAJORITY_OF)
[style] ~28-~28: ‘a majority of’ might be wordy. Consider a shorter alternative.
Context: ...ee may take action without a meeting if a majority of non-conflicted members express agreemen...(EN_WORDINESS_PREMIUM_A_MAJORITY_OF)
[style] ~28-~28: ‘A majority of’ might be wordy. Consider a shorter alternative.
Context: ... quorum of the non-conflicted members. A majority of non-conflicted members shall be deemed ...(EN_WORDINESS_PREMIUM_A_MAJORITY_OF)
docs/000-onboarding/where-to-contribute.md (1)
1-3
: Under Construction Notice
The document is marked as under construction, which is acceptable for an initial draft. As you add content, ensure that the document’s structure and information are updated to provide clear guidance to new contributors.docs/000-onboarding/how-to-contribute.md (1)
1-3
: Document Under Construction NoticeThe placeholder message clearly informs readers that the document is under construction. Consider including an estimated timeline or a brief note about the intended content to set expectations.
docs/030-project-vision-strategy-goals/ROADMAP.md (1)
1-3
: Under Construction Status AcknowledgedThe "under construction" notice is clear and serves its purpose well. In the future, an outline or a brief roadmap overview might further enhance the reader’s anticipation of upcoming content.
docs/000-onboarding/documentarian-onboarding-guide.md (1)
1-3
: Clear In-Progress NotificationThe document effectively communicates its in-progress status. When content becomes available, ensuring the placeholder is replaced with substantive guidance will improve usability.
docs/010-contribution-guidelines/git-workflow.md (1)
43-50
: Valuable Configuration TipsThe guidance on configuring the upstream remote includes a helpful tip and a link to an example script. It might be beneficial to periodically review that the external script URL remains accessible, or consider archiving a version in the repository.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (23)
GOVERNANCE.md
(1 hunks)TWEET_TOGETHER.md
(0 hunks)docs/000-onboarding/docs-onboarding-checklist.md
(1 hunks)docs/000-onboarding/documentarian-onboarding-guide.md
(1 hunks)docs/000-onboarding/how-to-contribute.md
(1 hunks)docs/000-onboarding/where-to-contribute.md
(1 hunks)docs/010-contribution-guidelines/git-workflow.md
(1 hunks)docs/020-governance-and-policies/TSC_MEMBERSHIP.md
(1 hunks)docs/020-governance-and-policies/WORKING_GROUPS.md
(1 hunks)docs/030-project-vision-strategy-goals/ROADMAP.md
(1 hunks)docs/060-meetings-and-communication/MEETINGS_ORGANIZATION.md
(3 hunks)docs/070-marketing/social-media-communication-guidelines.md
(1 hunks)docs/CODE_OF_CONDUCT_COMMITTEE.md
(1 hunks)docs/community-glossary.md
(1 hunks)git-workflow.md
(0 hunks)tweets/asyncapi-conference.tweet
(0 hunks)tweets/brand-audit-questionnaire.tweet
(0 hunks)tweets/conference-tracks.tweet
(0 hunks)tweets/contributor-summit-2021.tweet
(0 hunks)tweets/k8s-reviewers-needed.tweet
(0 hunks)tweets/looking-for-release-coordinator-2_5.tweet
(0 hunks)tweets/made-by-technology.tweet
(0 hunks)tweets/transparency-as-a-value.tweet
(0 hunks)
💤 Files with no reviewable changes (10)
- tweets/brand-audit-questionnaire.tweet
- tweets/made-by-technology.tweet
- tweets/k8s-reviewers-needed.tweet
- tweets/transparency-as-a-value.tweet
- tweets/looking-for-release-coordinator-2_5.tweet
- tweets/contributor-summit-2021.tweet
- tweets/conference-tracks.tweet
- git-workflow.md
- tweets/asyncapi-conference.tweet
- TWEET_TOGETHER.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/060-meetings-and-communication/MEETINGS_ORGANIZATION.md
47-47: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
51-51: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
58-58: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
62-62: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
66-66: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
70-70: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
74-74: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
84-84: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
88-88: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
92-92: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
94-94: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
96-96: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
100-100: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
104-104: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
110-110: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
117-117: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
121-121: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
125-125: Images should have alternate text (alt text)
null
(MD045, no-alt-text)
🪛 LanguageTool
docs/CODE_OF_CONDUCT_COMMITTEE.md
[style] ~28-~28: ‘a majority of’ might be wordy. Consider a shorter alternative.
Context: ...manent action shall require approval of a majority of non-conflicted members of the CoC Commi...
(EN_WORDINESS_PREMIUM_A_MAJORITY_OF)
[style] ~28-~28: ‘a majority of’ might be wordy. Consider a shorter alternative.
Context: ...ee may take action without a meeting if a majority of non-conflicted members express agreemen...
(EN_WORDINESS_PREMIUM_A_MAJORITY_OF)
[style] ~28-~28: ‘A majority of’ might be wordy. Consider a shorter alternative.
Context: ... quorum of the non-conflicted members. A majority of non-conflicted members shall be deemed ...
(EN_WORDINESS_PREMIUM_A_MAJORITY_OF)
docs/020-governance-and-policies/WORKING_GROUPS.md
[grammar] ~32-~32: Did you mean the communication tool “Slack” (= proper noun, capitalized)?
Context: ...(../../WORKING_GROUPS.yaml) file in the slack.channel.handle
field. Example: `#wg-de...
(ON_SKYPE)
GOVERNANCE.md
[style] ~20-~20: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ive community for everyone to thrive. * Make sure AsyncAPI is economically viable, i...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~25-~25: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...rs, etc. * Must be a servant leader and has no power other than the specified in th...
(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)
🔇 Additional comments (14)
docs/070-marketing/social-media-communication-guidelines.md (1)
1-1
: Under Construction Notice Appropriateness
The opening line clearly indicates that the document is under construction. This helps set readers' expectations.docs/020-governance-and-policies/TSC_MEMBERSHIP.md (1)
107-110
: Link Update Verification in "TSC_MEMBERSHIP.md"
The hyperlink for the “Slack Etiquette” document has been updated to use the new relative path (../060-meetings-and-communication/slack-etiquette.md
). This change aligns with the new directory structure proposed in the PR. Please verify that the target file indeed exists at that location.docs/020-governance-and-policies/WORKING_GROUPS.md (2)
30-32
: Consistent Update of WORKING_GROUPS Links
The links to theWORKING_GROUPS.yaml
file have been revised to use the new relative path (../../WORKING_GROUPS.yaml
). This update ensures that contacts (e.g., the working group's handle, GitHub team mentions, and Slack channel information) reference the correct file location. Please double-check that these paths resolve correctly in the reorganized repository.🧰 Tools
🪛 LanguageTool
[grammar] ~32-~32: Did you mean the communication tool “Slack” (= proper noun, capitalized)?
Context: ...(../../WORKING_GROUPS.yaml) file in theslack.channel.handle
field. Example: `#wg-de...(ON_SKYPE)
34-35
: Revised "Slack Etiquette" Reference in Working Group Section
The block quote has been updated with the new link to the "Slack Etiquette" document. This update not only maintains consistency with the changes in the TSC membership document but also enhances navigability for users seeking etiquette guidance.docs/CODE_OF_CONDUCT_COMMITTEE.md (2)
24-24
: Updated Conflict of Interest Link
The link to the Conflict of Interest policy now correctly points to./COC-incident-resolution-procedures.md#conflicts-of-interest
. This update improves navigability in line with the new documentation structure.
36-36
: Revised Incident Resolution Procedures Link
The link to the Incident Resolution Procedures has been updated to./COC-incident-resolution-procedures.md
. Please verify that the relative link functions correctly within the restructured repository.docs/000-onboarding/docs-onboarding-checklist.md (2)
15-16
: Updated Relative Links for Contribution GuidelinesThe relative links for "[technical writer contributor responsibilities]" and "[prerequisite knowledge topics]" have been updated to reflect the new directory structure. Please verify that these links resolve correctly in the rendered document.
1-14
: Checklist Structure and Content ReviewThe overall checklist is well-organized and clearly guides new contributors through essential onboarding steps. Ensure that all external and internal links remain current as the documentation evolves.
Also applies to: 17-23
docs/010-contribution-guidelines/git-workflow.md (6)
1-8
: Comprehensive Introduction and OverviewThe introductory section sets a solid context for the Git workflow, explaining the fork model clearly for all contributors. The information is thorough and accessible.
9-17
: Clear and Concise Rules SectionThe rules are presented in a clear, bullet-point format that makes the guidelines easy to follow. This clarity helps in reinforcing best practices among contributors.
26-41
: Detailed Fork and Clone InstructionsThe clone and fork instructions, along with command examples, are detailed and will likely be very useful for new contributors. The step-by-step nature of these instructions enhances clarity.
52-108
: Thorough Manual Configuration DocumentationThe manual configuration section breaks down each command with expected outputs, making it very accessible, especially for contributors less familiar with Git. This detailed approach is commendable.
109-113
: Helpful GitHub UI Synchronization InstructionsThe instructions for using the GitHub UI, with a link to the official documentation, are appropriate. Keeping a note about potential UI changes in the future might be helpful.
114-131
: Effective Start Contributing GuidanceThe final section outlining branch creation, commit formatting (with reference to Conventional Commits), and push instructions is clear and actionable. This practical guidance will assist contributors in aligning with the repository's standards.
Description
The structure proposed in this PR looks as follows:
Related issue(s)
Summary by CodeRabbit
Documentation
Chores