docs: replace duplicated content with reusable fragments #3269
Conversation
bandantonio
requested review from
quetzalliwrites,
derberg,
akshatnema,
magicmatatjahu,
Mayaleeeee,
asyncapi-bot-eve,
thulieblack and
anshgoyalevil
as code owners
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
✅ Deploy Preview for asyncapi-website ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
asyncapi-bot
requested review from
devilkiller-ag,
sambhavgupta0705,
BhaswatiRoy,
J0SAL,
TRohit20 and
VaishnaviNandakumar
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-3269--asyncapi-website.netlify.app/ |
There was a problem hiding this comment.
Thanks @bandantonio a lot! Can you explain why you didn't put new fragments in the same location we keep others: https://github.com/asyncapi/website/tree/master/assets/docs/fragments any why you need to use mdx extension?
WalkthroughThe changes in this pull request focus on enhancing the documentation for the AsyncAPI project by introducing reusable Markdown components for contribution guidelines. A new section titled "Use shared Markdown fragments" was added to the Changes
Assessment against linked issues
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
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Outside diff range and nitpick comments (24)
assets/docs/fragments/how-to-contribute.md (2)
4-7: Great improvement in document structure and tone!The new introductory sentence adds a welcoming touch to the document. The use of the
DocContributionNotescomponent is an excellent way to implement the reusable fragments strategy.Consider enhancing the introductory sentence slightly for more impact:
-Did you know that you can contribute Docs to AsyncAPI as well? +Did you know that you can contribute to AsyncAPI Docs as well? Here's how you can get started:This change provides a smoother transition to the
DocContributionNotescomponent.
9-10: Excellent addition to encourage engagement!The "Talk to me" section with the
TalkToMecomponent is a great way to encourage communication with potential contributors. Its placement at the end of the document serves as an effective call-to-action.Consider making the section heading more specific:
-### Talk to me +### Get in TouchThis change makes the purpose of the section slightly clearer and more professional.
markdown/docs/guides/index.md (1)
Line range hint
1-15: Consider SEO impact and ensure comprehensive fragment content.The changes successfully implement the use of a reusable fragment, which aligns with the PR objectives. However, please consider the following points:
- Ensure that the
DocContributionNotesfragment contains all the necessary information that was previously in this file.- Consider the potential impact on SEO due to the reduction of content in this file. You may want to add more contextual information around the
<DocContributionNotes />component to maintain keyword relevance.To mitigate potential SEO issues, consider adding a brief introduction before the
<Remember>block that summarizes the importance of contributions and uses relevant keywords.markdown/docs/concepts/index.md (1)
15-15: LGTM: Reusable component for contribution notes.The
<DocContributionNotes />component is correctly used and placed within the<Remember>block, effectively replacing the previously duplicated content. This change aligns well with the PR objective of reducing duplication and improving maintainability.Consider adding a brief introductory sentence before the component to provide context, such as:
Here are some guidelines for contributing to AsyncAPI documentation: <DocContributionNotes />This addition would help readers understand what to expect from the component.
markdown/docs/community/index.md (1)
8-8: Consider removing the colon from the heading.To improve consistency and adhere to common Markdown style guidelines, consider removing the colon from the heading.
Suggested change:
-## Community: Guidelines and resources around community. +## Community - Guidelines and resources around community🧰 Tools
🪛 Markdownlint
8-8: Punctuation: '.'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
markdown/docs/tools/index.md (2)
6-6: LGTM! Consider using a more specific import alias.The import of
DocContributionNotesaligns well with the PR objective of using reusable fragments to reduce duplication. This approach will help maintain a single source of truth for contribution guidelines.Consider using a more specific import alias to improve code readability:
-import DocContributionNotes from '@/assets/docs/fragments/contribution-notes.md'; +import DocContributionNotes from '@/assets/docs/fragments/DocContributionNotes.md';This change would make it clearer that we're importing a specific component rather than the entire file content.
6-15: Excellent work on improving documentation maintainability!These changes effectively address the PR objectives by replacing duplicated content with a reusable fragment. This approach:
- Improves maintainability by centralizing contribution information.
- Allows for easier updates to contribution guidelines across all documentation.
- Adheres to the DRY (Don't Repeat Yourself) principle.
- Simplifies the document structure.
To further improve this architectural change:
- Consider creating a dedicated directory for reusable documentation fragments if it doesn't already exist.
- Document the usage of these reusable fragments in your contribution guidelines to ensure consistent adoption by future contributors.
assets/docs/fragments/contribution-notes.md (2)
3-9: Excellent onboarding steps for new contributors.This section provides clear, actionable steps for new contributors to get started. It effectively guides them through the process and encourages engagement.
Consider adding a brief note about the typical response time for comments or PRs to set expectations for new contributors. For example:
5. Once you've commented or opened a PR, our team typically responds within 2-3 business days. We appreciate your patience and contribution!
1-14: Overall excellent addition to the documentation.This new file successfully addresses the PR objectives by creating a reusable fragment for contribution notes. It effectively streamlines the documentation process, provides clear guidance for new contributors, and resolves the linked issues.
Key achievements:
- Emphasizes the importance of documentation contributions.
- Provides clear steps for new contributors to get started.
- Addresses common questions and provides contact information.
- Resolves issue docs: updated handle link of alequetzalli #3185 by updating the GitHub handle.
To further improve maintainability, consider creating separate fragments for each main section (introduction, getting started steps, and FAQ). This would allow for even more granular reuse and easier updates in the future.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~1-~1: This verb does not appear to agree with the subject. Consider using a different form.
Context: ... OSS; Dev Docs are a huge help that benefit the entire OSS ecosystem. At AsyncAPI, ...(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)
[uncategorized] ~12-~12: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ave a documentation contributor question and you're wondering how to tag me into a G...(COMMA_COMPOUND_SENTENCE)
markdown/blog/2023-may-docs-report.md (2)
77-78: LGTM! Consider adding a brief introduction.The addition of this section about contributing to AsyncAPI Docs is valuable and aligns well with the PR objectives. The use of the
DocContributionNotescomponent is an excellent example of leveraging reusable fragments.Consider adding a brief introductory sentence before the component to provide context. For example:
## How to contribute to AsyncAPI Docs Did you know that you can contribute Docs to AsyncAPI as well? +Here's how you can get started: <DocContributionNotes />
Line range hint
1-82: Excellent improvements to documentation structure and content!The changes in this file significantly enhance the documentation by:
- Implementing reusable components (
DocContributionNotesandTalkToMe), which aligns with the DRY principle and improves maintainability.- Adding sections that encourage community contribution and engagement.
- Improving the visual consistency of the mermaid graph.
These changes align perfectly with the PR objectives and contribute to a more robust and user-friendly documentation system.
Consider applying similar changes to other documentation files to maintain consistency across the entire documentation set. This could involve:
- Identifying other instances of duplicated content that could be replaced with reusable fragments.
- Ensuring that the "How to contribute" and "Talk to me" sections are consistently present in relevant documentation files.
- Standardizing the use of mermaid graphs across documentation where applicable.
markdown/blog/2023-july-docs-report.md (1)
GitHub handle update for alequetzalli is missing in this file
The GitHub handle for Alejandra Quetzalli has not been updated in
markdown/blog/2023-july-docs-report.md. Please make the necessary changes to address issue #3185.🔗 Analysis chain
Line range hint
1-97: Verification of linked issues resolutionThe changes in this file effectively address the deduplication of content through the use of reusable fragments, which aligns with the objectives of issue #3261. Great job on implementing this improvement!
However, I couldn't find any changes related to updating the GitHub handle link for user alequetzalli (issue #3185) in this file. Could you please clarify if this update was made in other files or if it's still pending?
To confirm the resolution of issue #3185, we can run the following script:
This will help us verify if the GitHub handle has been updated across the documentation.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Search for occurrences of alequetzalli's GitHub handle rg -i 'alequetzalli' --type mdLength of output: 5556
markdown/blog/changes-coming-docs.md (2)
26-26: Approved: Simplified introduction improves clarity.The removal of the phrase "as primary owner for our AsyncAPI Dev Docs 📄" simplifies the introduction without losing essential information. This change may help avoid potential confusion about ownership within the open-source community.
Consider adding a brief mention of your focus on AsyncAPI documentation to maintain context:
-I'm a Senior Technical Writer 👩🏻💻 recently hired by [Postman](https://www.postman.com/alejandra-quetzalli) to focus solely on the Open-Source (OSS) [AsyncAPI initiative](https://www.asyncapi.com/). +I'm a Senior Technical Writer 👩🏻💻 recently hired by [Postman](https://www.postman.com/alejandra-quetzalli) to focus solely on the Open-Source (OSS) [AsyncAPI initiative](https://www.asyncapi.com/), with a primary emphasis on documentation.
Line range hint
55-59: Approved: Enhanced documentation structure aligns with best practices.The additions provide more concrete information about the planned improvements to the documentation structure. The new content buckets, including "How-To", and the introduction of the Diátaxis Framework as justification for the new structure, align well with industry best practices and the PR objectives.
Consider adding a brief explanation of the "Tools" bucket mentioned earlier in the list:
- Tools +- Tools: Documentation for AsyncAPI-related tools and utilities. Why, you wonder?This addition would provide a complete overview of all new content buckets.
Also applies to: 75-75, 78-79
🧰 Tools
🪛 LanguageTool
[uncategorized] ~58-~58: A comma may be missing after the conjunctive/linking adverb ‘Currently’.
Context: ... content bucket. - A tools section! Currently we have documentation for our tools in ...(SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA)
🪛 Markdownlint
51-51: Expected: h3; Actual: h4
Heading levels should only increment by one level at a time(MD001, heading-increment)
markdown/blog/2023-Q4-docs-report.md (3)
38-42: LGTM: Enhanced GSoD project descriptionsThe expanded descriptions of the Google Season of Docs 2023 projects provide valuable context and clarity. This aligns well with the PR's objective of enhancing documentation.
Consider adding hyperlinks to the mentioned resources for easier navigation:
- Link "AsyncAPI Killercoda profile" to https://killercoda.com/asyncapi/
- Link the learning paths repository to https://github.com/asyncapi/learning-paths
🧰 Tools
🪛 LanguageTool
[style] ~39-~39: This phrase is redundant. Consider writing “facilitate”.
Context: ...n guidelines for AsyncAPI documents. To facilitate easier implementation of Event-Driven Architec...(FACILITATE_EASIER)
Line range hint
61-73: LGTM: Enhanced conclusion with visual representationThe expanded conclusion provides a comprehensive summary of the Q4 achievements, and the addition of the mermaid diagram offers a visual representation of the key points. These changes significantly enhance the overall clarity and engagement of the report.
Consider adding a brief text introduction before the mermaid diagram to provide context for readers who may be unfamiliar with this type of visualization. For example:
"The following diagram summarizes the key achievements and focus areas of AsyncAPI Docs in Q4 2023:"
39-39: Consider simplifying the phrase "facilitate easier"The phrase "facilitate easier" is redundant, as "facilitate" already implies making something easier or more convenient. Consider simplifying it to just "facilitate" for improved clarity and conciseness.
Suggested change:
- To facilitate easier implementation of Event-Driven Architectures (EDAs), our documentation needs to provide more comprehensive explanations of the different sections within an AsyncAPI document. + To facilitate implementation of Event-Driven Architectures (EDAs), our documentation needs to provide more comprehensive explanations of the different sections within an AsyncAPI document.🧰 Tools
🪛 LanguageTool
[style] ~39-~39: This phrase is redundant. Consider writing “facilitate”.
Context: ...n guidelines for AsyncAPI documents. To facilitate easier implementation of Event-Driven Architec...(FACILITATE_EASIER)
markdown/blog/2023-june-docs-report.md (2)
Line range hint
48-76: LGTM: AsyncAPI Docs' Hall of Fame section addedThe addition of the AsyncAPI Docs' Hall of Fame section is a great way to recognize significant contributors to the documentation effort. The mermaid diagram enhances the visual appeal and readability of the information.
Consider adding a brief explanation of how inductees are chosen for the Hall of Fame to provide context for readers and potential future contributors.
🧰 Tools
🪛 LanguageTool
[grammar] ~49-~49: The plural noun “congratulations” cannot be used with the article “A”. Did you mean “A hearty congratulation” or “hearty congratulations”?
Context: ... writing maintainers and contributors! A hearty congratulations to [Florence Njeri](https://github.com/...(A_NNS)
Line range hint
1-130: LGTM: Overall structure and content improvementsThe changes to this document align well with the PR objectives. The addition of the AsyncAPI Docs' Hall of Fame section provides more value to readers, and the use of reusable components (DocContributionNotes and TalkToMe) improves maintainability and consistency across the documentation.
Consider adding a brief introduction to the new Hall of Fame section in the "AsyncAPI Docs - June Summary" to highlight this new feature.
markdown/blog/2023-Q1-docs-report.md (4)
83-83: LGTM: Improved clarity in GSoD 2023 description.The rephrasing enhances readability while maintaining the essential information. To further improve clarity, consider adding a brief explanation of what the two projects entail:
- AsyncAPI is one of 13 OSS organizations accepted into Google Season of Docs 2023! Selected technical writers will work on two projects: **documenting the AsyncAPI document in detail** and **creating interactive learning paths**. + AsyncAPI is one of 13 OSS organizations accepted into Google Season of Docs 2023! Selected technical writers will work on two projects: **documenting the AsyncAPI document in detail** (providing comprehensive explanations of the AsyncAPI specification) and **creating interactive learning paths** (developing engaging, hands-on tutorials for users to learn AsyncAPI).
92-92: LGTM: Updated application count, but consider future-proofing.The update to the number of applications received is good for keeping the blog post current. However, this information may become outdated quickly. Consider one of these approaches:
- Add a "last updated" date next to this information.
- Replace the specific number with a more general statement that won't need frequent updates.
For example:
We have received numerous applications to date. For the most current count, please check our [GSoD 2023 status page](insert_link_here).This way, the blog post remains informative without requiring frequent updates.
157-157: LGTM: Minor formatting adjustment in mermaid graph.The change in the mermaid graph syntax is a minor formatting adjustment that doesn't affect the content or structure of the graph. While this change is fine, consider using a Markdown or mermaid-specific linter in the future to automatically handle such formatting adjustments. This would ensure consistency across all diagrams and reduce the need for manual formatting changes.
180-180: LGTM: Added reusable TalkToMe component.The addition of the
TalkToMecomponent is another excellent use of reusable fragments, aligning with the PR objectives. This approach ensures consistency in contact information across the documentation.Consider adding a brief introduction before the component to provide context:
+ ### Get in touch <TalkToMe />This small addition would help readers understand the purpose of the following content.
README.md (1)
137-154: Great addition: Instructions for using shared Markdown fragmentsThis new section effectively addresses the PR objective of replacing duplicated content with reusable fragments. It provides clear instructions on how to use shared Markdown fragments, which will help maintain consistency and reduce duplication in the documentation.
Consider adding a brief explanation of the benefits of using shared fragments (e.g., consistency, easier maintenance) to reinforce the importance of this feature.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (21)
- README.md (6 hunks)
- assets/docs/fragments/contribution-notes.md (1 hunks)
- assets/docs/fragments/how-to-contribute.md (1 hunks)
- assets/docs/fragments/talk-to-me.md (1 hunks)
- markdown/blog/2023-April-docs-report.md (4 hunks)
- markdown/blog/2023-Q1-docs-report.md (6 hunks)
- markdown/blog/2023-Q4-docs-report.md (5 hunks)
- markdown/blog/2023-july-docs-report.md (5 hunks)
- markdown/blog/2023-june-docs-report.md (4 hunks)
- markdown/blog/2023-may-docs-report.md (3 hunks)
- markdown/blog/changes-coming-docs.md (5 hunks)
- markdown/blog/google-season-of-docs-2022.md (3 hunks)
- markdown/docs/community/index.md (1 hunks)
- markdown/docs/concepts/asyncapi-document/adding-bindings.md (3 hunks)
- markdown/docs/concepts/index.md (1 hunks)
- markdown/docs/guides/index.md (1 hunks)
- markdown/docs/reference/bindings/index.md (1 hunks)
- markdown/docs/reference/index.md (1 hunks)
- markdown/docs/tools/index.md (1 hunks)
- markdown/docs/tutorials/generate-code.md (5 hunks)
- markdown/docs/tutorials/index.md (2 hunks)
✅ Files skipped from review due to trivial changes (2)
- assets/docs/fragments/talk-to-me.md
- markdown/docs/tutorials/generate-code.md
🧰 Additional context used
🪛 LanguageTool
assets/docs/fragments/contribution-notes.md
[uncategorized] ~1-~1: This verb does not appear to agree with the subject. Consider using a different form.
Context: ... OSS; Dev Docs are a huge help that benefit the entire OSS ecosystem. At AsyncAPI, ...(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)
[uncategorized] ~12-~12: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ave a documentation contributor question and you're wondering how to tag me into a G...(COMMA_COMPOUND_SENTENCE)
markdown/blog/2023-Q4-docs-report.md
[style] ~39-~39: This phrase is redundant. Consider writing “facilitate”.
Context: ...n guidelines for AsyncAPI documents. To facilitate easier implementation of Event-Driven Architec...(FACILITATE_EASIER)
🪛 Markdownlint
markdown/blog/google-season-of-docs-2022.md
78-78: Column: 21
Hard tabs(MD010, no-hard-tabs)
80-80: Column: 16
Hard tabs(MD010, no-hard-tabs)
markdown/docs/community/index.md
8-8: Punctuation: '.'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
🔇 Additional comments (59)
assets/docs/fragments/how-to-contribute.md (2)
1-2: LGTM! Excellent use of modular components.The addition of these import statements aligns perfectly with the PR objective of replacing duplicated content with reusable fragments. This approach will significantly improve maintainability and consistency across the documentation.
1-10: Excellent restructuring of the contribution guidelines!The changes made to this file significantly improve the documentation's maintainability and consistency. The use of modular components (
DocContributionNotesandTalkToMe) aligns perfectly with the PR objective of replacing duplicated content with reusable fragments.To ensure the changes are effective across the documentation:
- Verify that the imported components (
DocContributionNotesandTalkToMe) contain the necessary information previously found in this file.- Check other documentation files to confirm that they are also using these new components where appropriate.
Run the following script to help with this verification:
This script will help ensure that the new components are properly implemented and used consistently across the documentation.
✅ Verification successful
Verification Successful: New Components are Properly Implemented and Utilized
All imported components (
DocContributionNotesandTalkToMe) contain the necessary information and are consistently used across relevant documentation files.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Verify the usage of new components across documentation files # Test 1: Check content of the new component files echo "Content of DocContributionNotes:" cat assets/docs/fragments/contribution-notes.md echo -e "\nContent of TalkToMe:" cat assets/docs/fragments/talk-to-me.md # Test 2: Search for usage of new components in other markdown files echo -e "\nUsage of DocContributionNotes in other files:" rg --type md "import.*DocContributionNotes" -g '!assets/docs/fragments/*' echo -e "\nUsage of TalkToMe in other files:" rg --type md "import.*TalkToMe" -g '!assets/docs/fragments/*'Length of output: 4405
markdown/docs/reference/index.md (3)
Line range hint
1-18: Excellent work on improving documentation maintainability!The changes in this file effectively implement the PR's objective of replacing duplicated content with reusable fragments. By moving the contribution notes to a separate file and importing them as a component, you've adhered to the DRY principle and created a single source of truth for this information.
These modifications will make it easier to maintain consistent contribution guidelines across the documentation. The overall structure and purpose of the document remain intact, preserving its readability and usefulness.
Great job on this improvement!
15-15: LGTM! Verify the component's content.The use of the
<DocContributionNotes />component effectively replaces the previously detailed contribution section, aligning with the PR's goal of reducing duplication. This change should improve consistency across the documentation and make future updates easier.To ensure the component contains all necessary information, please run the following verification script:
#!/bin/bash # Display the content of the contribution-notes.md file fd -t f 'contribution-notes.md' | xargs catThis script will output the content of the 'contribution-notes.md' file. Please review the output to confirm that all essential contribution guidelines are included.
6-6: LGTM! Verify the import path.The addition of this import statement aligns well with the PR objective of using reusable fragments for documentation. This approach will help reduce duplication and improve maintainability.
To ensure the import path is correct, please run the following verification script:
This script will search for the 'contribution-notes.md' file in the project directory structure. If the file exists in the correct location, the script should output its path.
✅ Verification successful
Action Required: Corrected Verification Script
To ensure the import path is correct, please run the following verification script:
This script checks for the existence of
contribution-notes.mdwithin theassets/docs/fragmentsdirectory. It provides clear output indicating whether the file exists in the expected location.
Import Path Verified
The import path for
contribution-notes.mdinmarkdown/docs/reference/index.mdis correct and points to the existing file inassets/docs/fragments.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Verify the existence of the imported file fd -t f 'contribution-notes.md' | grep 'assets/docs/fragments'Length of output: 1328
Script:
#!/bin/bash # Verify the existence of the imported file fd -t f 'contribution-notes.md' | grep 'assets/docs/fragments' >/dev/null 2>&1 if [ $? -eq 0 ]; then echo "Verification Passed: 'contribution-notes.md' exists in 'assets/docs/fragments'." else echo "Verification Failed: 'contribution-notes.md' not found in 'assets/docs/fragments'." fiLength of output: 259
markdown/docs/tutorials/index.md (3)
6-6: LGTM: Import statement for reusable fragment.The import statement for
DocContributionNotesaligns well with the PR objective of replacing duplicated content with reusable fragments. This approach promotes maintainability and consistency across the documentation.
Line range hint
1-16: Summary: Effective implementation of reusable documentation fragment.The changes in this file successfully implement the use of a reusable fragment for contribution notes, aligning well with the PR objectives and addressing issue #3261. This approach will help maintain consistency across the documentation and improve maintainability by centralizing the contribution information.
A few points to consider:
- Ensure that the
DocContributionNotescomponent includes all necessary information from the original detailed section.- Verify if the GitHub handle update mentioned in issue docs: updated handle link of alequetzalli #3185 is addressed within the component.
- Consider adding a comment explaining the purpose of the
DocContributionNotescomponent for future maintainers.Overall, this change is a positive step towards more maintainable and consistent documentation.
16-16: Verify contents of<DocContributionNotes />component.The use of the
<DocContributionNotes />component effectively replaces the previously detailed contribution section, aligning with the PR objective of reducing duplication. This approach will help maintain consistency across the documentation.However, please ensure that all essential information from the original detailed section (such as steps for getting started, links to the Contribution Guide and Code of Conduct, and instructions for engaging with issues) is included in the new component.
To verify the contents of the new component, please run the following script:
✅ Verification successful
Contents of
<DocContributionNotes />verified.The
<DocContributionNotes />component includes all essential contribution information as per the original section, ensuring consistency and reducing duplication in the documentation.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Display the contents of the DocContributionNotes component # Test: Output the contents of the contribution-notes.md file cat assets/docs/fragments/contribution-notes.mdLength of output: 1240
markdown/docs/guides/index.md (2)
6-6: LGTM: Import statement for reusable fragment added.The import statement for
DocContributionNotesis correctly added, aligning with the PR objective of using reusable fragments to reduce duplication in the documentation.
15-15: Verify content of the reusable fragment.The use of
<DocContributionNotes />component aligns with the PR objective of reducing duplication. However, please ensure that the content in the reusable fragment (@/assets/docs/fragments/contribution-notes.md) includes all necessary information that was previously in this file, such as:
- The importance of documentation contributions
- Links to the Contribution Guide and Code of Conduct
- Reference to the AsyncAPI Docs Board
To verify the content of the reusable fragment, please run the following script:
✅ Verification successful
Reusable Fragment Content Verified
The
<DocContributionNotes />component includes all necessary information:
- The importance of documentation contributions
- Links to the Contribution Guide and Code of Conduct
- Reference to the AsyncAPI Docs Board
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Verify the content of the contribution-notes.md fragment # Test: Check if the fragment file exists and display its content cat assets/docs/fragments/contribution-notes.md # Test: Search for important keywords in the fragment echo "Checking for important keywords:" rg -i "contribution guide|code of conduct|asyncapi docs board" assets/docs/fragments/contribution-notes.mdLength of output: 1739
markdown/docs/concepts/index.md (2)
Line range hint
1-15: Summary: Successful implementation of reusable fragmentThe changes in this file effectively implement the reusable fragment for contribution notes, aligning perfectly with the PR objectives. By replacing the duplicated content with the
<DocContributionNotes />component, you've successfully:
- Reduced duplication across documentation files.
- Improved maintainability by centralizing the contribution information.
- Adhered to the DRY principle as mentioned in issue [📑 Docs]: Deduplicate content and replace it with reusable fragments #3261.
These changes contribute significantly to streamlining the documentation process. Great job on implementing this improvement!
6-6: LGTM: Import statement for reusable fragment.The import statement for
DocContributionNotesis correctly formatted and aligns with the PR objective of using reusable fragments to reduce duplication.To ensure the import path is correct, please run the following script:
This script will search for the
contribution-notes.mdfile in the project directory. If the file exists, the import path is likely correct.✅ Verification successful
Verified: Import path is correct.
The import path for
DocContributionNotesinmarkdown/docs/concepts/index.mdcorrectly points toassets/docs/fragments/contribution-notes.md, ensuring proper integration of the reusable fragment.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Verify the existence of the imported file fd -t f contribution-notes.mdLength of output: 75
markdown/docs/community/index.md (3)
6-6: LGTM: Import statement for reusable fragment.The import of
DocContributionNotesaligns with the PR objective of replacing duplicated content with reusable fragments. This change supports the DRY principle and improves maintainability.
Line range hint
1-15: Overall changes improve maintainability and adhere to DRY principle.The changes in this file successfully implement the use of a reusable fragment for contribution notes, aligning with the PR objectives. This approach improves maintainability and adheres to the DRY principle.
To ensure a smooth transition, please verify the following:
- The content of
DocContributionNotesincludes all necessary information previously present in this file.- The reusable fragment is consistently used across all relevant documentation files.
- The new structure maintains or improves the readability of the documentation.
Run the following script to check for consistency across documentation files:
#!/bin/bash # Description: Check for consistent usage of DocContributionNotes across documentation files # Test: Search for files using DocContributionNotes echo "Files using DocContributionNotes:" rg --type md "import DocContributionNotes from '@/assets/docs/fragments/contribution-notes.md'" docs echo "\nFiles still containing old contribution notes:" rg --type md "## Contribute to the AsyncAPI" docs | grep -v "DocContributionNotes"🧰 Tools
🪛 Markdownlint
8-8: Punctuation: '.'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
15-15: Verify content of the reusable component.The usage of
<DocContributionNotes />effectively replaces the detailed contribution section, aligning with the PR objectives. This change simplifies the document and centralizes the contribution guidelines.Please ensure that the content of
DocContributionNotesin@/assets/docs/fragments/contribution-notes.mdcovers all necessary information previously included in this section. Run the following script to verify the content:✅ Verification successful
Content of
<DocContributionNotes />VerifiedThe
DocContributionNotescomponent in@/assets/docs/fragments/contribution-notes.mdincludes all necessary information previously detailed inmarkdown/docs/community/index.md. This replacement effectively centralizes the contribution guidelines without omitting any essential details.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Verify the content of the contribution notes fragment # Test: Display the content of the contribution notes fragment cat assets/docs/fragments/contribution-notes.mdLength of output: 465
Script:
#!/bin/bash # Description: Search for the location of contribution-notes.md within the repository # Search for all instances of contribution-notes.md fd 'contribution-notes\.md$' .Length of output: 78
Script:
#!/bin/bash # Description: Display the content of the contribution notes fragment cat assets/docs/fragments/contribution-notes.mdLength of output: 1240
markdown/docs/reference/bindings/index.md (1)
8-8: Approve the import path change and verify alias configuration.The change from a relative import path to an alias-based import path (
@/assets/docs/fragments/bindings-overview.md) is a good improvement. It simplifies the import statement and makes it less prone to errors when files are moved.This change aligns well with the PR objective of improving maintainability and using reusable fragments.
To ensure this change works as expected, please verify that the
@alias is properly configured in your project's build system. You can run the following script to check for other files that might need similar updates:If the script returns results, consider updating those files similarly for consistency across the project.
assets/docs/fragments/contribution-notes.md (1)
10-11: Clear section header for contributor questions.This header effectively introduces the section for addressing common questions from documentation contributors.
markdown/docs/concepts/asyncapi-document/adding-bindings.md (2)
8-8: LGTM! Correct usage of the BindingsOverview component.The
BindingsOverviewcomponent is correctly used as a self-closing tag immediately after the import statement. This implementation effectively replaces duplicated content with a reusable fragment, aligning with the PR objectives.
32-32: Minor formatting improvements and consistency check.The removal of unnecessary line breaks in various sections of the document, such as the server bindings and message bindings explanations, improves readability. These changes are beneficial and do not alter the document's content or structure.
To ensure consistency between the imported
BindingsOverviewcomponent and the rest of the document, please run the following script:#!/bin/bash # Description: Verify consistency between BindingsOverview and the rest of the document # Test: Check for any duplicate content between BindingsOverview and this file rg --type md -A 10 -B 10 'BindingsOverview' assets/docs/fragments/bindings-overview.md markdown/docs/concepts/asyncapi-document/adding-bindings.mdThis script will help identify any potential duplication or inconsistencies between the reusable fragment and the main document.
Also applies to: 97-97
markdown/blog/2023-may-docs-report.md (3)
57-57: LGTM! Graph styling enhancement.The addition of the style definition for node D improves the visual consistency of the mermaid graph. The color and stroke settings align well with the existing node styles.
81-81: LGTM! Great addition for community engagement.The inclusion of the "Talk to me" section with the
TalkToMecomponent is an excellent addition. It encourages community engagement and feedback, which is crucial for the continuous improvement of the documentation.
16-17: LGTM! Verify component imports.The addition of these import statements aligns well with the PR objective of replacing duplicated content with reusable fragments. This approach promotes maintainability and consistency across the documentation.
Let's verify that these components exist and are correctly imported:
✅ Verification successful
Verified: Imported components exist and are correctly referenced.
The imported files
DocContributionNotesandTalkToMeare present at the specified paths, confirming that the imports are accurate and functional.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Verify the existence of the imported components echo "Checking for DocContributionNotes component:" fd -e md -p "assets/docs/fragments/contribution-notes.md" echo "Checking for TalkToMe component:" fd -e md -p "assets/docs/fragments/talk-to-me.md"Length of output: 361
markdown/blog/2023-july-docs-report.md (6)
16-17: Great addition of reusable fragments!The import of
DocContributionNotesandTalkToMecomponents aligns perfectly with the PR objective of replacing duplicated content with reusable fragments. This change supports the DRY (Don't Repeat Yourself) principle and will help maintain consistency across the documentation.
31-32: Improved header formattingThe modification to the section header "2023 AsyncAPI Mentorship Program —
Technical Writing" enhances consistency and readability. The use of backticks for "Technical Writing" helps it stand out appropriately.
66-66: Enhanced Mermaid diagram consistencyThe addition of a style definition for node D in the Mermaid diagram improves visual consistency. This change ensures that all nodes in the graph have a uniform appearance, enhancing the overall readability of the diagram.
93-94: Effective use of reusable component for contribution notesThe introduction of the
DocContributionNotescomponent here is an excellent implementation of the PR's main objective. By replacing the static text with a reusable fragment, you're ensuring consistency across the documentation and making future updates easier to manage.
97-97: Excellent use of reusable component for community engagementThe introduction of the
TalkToMecomponent is a great way to standardize the community engagement section across different pages. This change aligns well with the PR's goal of reducing duplication and improving maintainability.
Line range hint
1-97: Overall improvements in structure and contentThe refinements made throughout the document enhance clarity and readability without altering the core content. These changes align well with the PR objective of improving the documentation. The consistent use of reusable components and the minor adjustments to phrasing contribute to a more maintainable and user-friendly document.
markdown/blog/changes-coming-docs.md (4)
17-18: LGTM! Imports align with PR objectives.The addition of these import statements for
DocContributionNotesandTalkToMecomponents aligns well with the PR objective of replacing duplicated content with reusable fragments. This approach will help in maintaining consistency across documentation and reduce redundancy.
Line range hint
1-132: Overall: Excellent improvements to documentation structure and consistency.The changes in this file significantly enhance the documentation by:
- Introducing reusable components for contribution notes and community engagement.
- Restructuring the content buckets to align with the Diátaxis Framework.
- Providing more detailed information about upcoming changes to the documentation.
These improvements align perfectly with the PR objectives of replacing duplicated content with reusable fragments and enhancing the overall documentation structure. The minor suggestions provided in the review comments will further refine the clarity and completeness of the content.
🧰 Tools
🪛 LanguageTool
[style] ~27-~27: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...y owner for our AsyncAPI Dev Docs 📄 . I also recently [joined our initiative's ...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
132-132: LGTM! Reusable component enhances community engagement.The use of the
TalkToMecomponent aligns well with the PR objective of replacing duplicated content with reusable fragments. This change will likely improve consistency across documentation for community engagement sections.To ensure the component contains all necessary information, please run the following script:
#!/bin/bash # Description: Verify the content of the TalkToMe component # Test: Check if the component file exists and display its content cat assets/docs/fragments/talk-to-me.md
128-129: LGTM! Reusable component improves consistency.The use of the
DocContributionNotescomponent aligns perfectly with the PR objective of replacing duplicated content with reusable fragments. This change will likely improve consistency across documentation for contribution guidelines.To ensure the component contains all necessary information, please run the following script:
✅ Verification successful
Apologies for the confusion in the previous script execution.
Please run the following corrected script to verify the content of the
DocContributionNotescomponent:
Apologies for the continued issues.
Please run the following corrected script to verify the content of the
DocContributionNotescomponent:
Apologies for the repeated issue.
Please run the following corrected script to accurately verify the content of the
DocContributionNotescomponent:
Apologies for the continued issues with the verification script.
Please run the following script to list all files in the
assets/docs/fragmentsdirectory and confirm the presence and correct naming of thecontribution-notes.mdfile:
Verified: DocContributionNotes component is correctly included and contains the expected content.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Verify the content of the DocContributionNotes component # Test: Check if the component file exists and display its content cat assets/docs/fragments/contribution-notes.mdLength of output: 461
Script:
#!/bin/bash # Description: Verify the content of the DocContributionNotes component # Test: Check if the component file exists and display its content cat assets/docs/fragments/contribution-notes.mdLength of output: 1240
Script:
#!/bin/bash # Description: Verify the content of the DocContributionNotes component # Test: Check if the component file exists and display its content cat assets/docs/fragments/contribution-notes.mdLength of output: 1240
Script:
#!/bin/bash # Description: Verify the content of the DocContributionNotes component # Test: Check if the component file exists and display its content cat assets/docs/fragments/contribution-notes.mdLength of output: 1240
Script:
#!/bin/bash # Description: List all files in the assets/docs/fragments directory ls -la assets/docs/fragments/Length of output: 485
markdown/blog/2023-Q4-docs-report.md (5)
14-14: LGTM: Improved excerpt clarityThe updated excerpt provides a more focused summary of the Q4 engagement, highlighting the primary content areas. This change aligns well with the PR's objective of enhancing documentation clarity.
47-49: LGTM: Improved Mentorship Program sectionThe revisions to the AsyncAPI 2023 Mentorship Program section enhance clarity and organization. The addition of the table provides a concise overview of the sample topics covered, which improves the overall readability of the document.
100-101: LGTM: Implemented reusable contribution notesThe use of the
DocContributionNotescomponent here is an excellent implementation of the PR's objective to replace duplicated content with reusable fragments. This change will ensure consistency in contribution guidelines across the documentation.
104-104: LGTM: Implemented reusable community engagement componentThe introduction of the
TalkToMecomponent is another excellent example of using reusable fragments to maintain consistency across the documentation. This aligns perfectly with the PR's objectives and will ensure that community engagement information is uniform throughout the AsyncAPI documentation.
17-18: LGTM: Added reusable componentsThe addition of
DocContributionNotesandTalkToMecomponents aligns perfectly with the PR's objective of replacing duplicated content with reusable fragments. This change will help maintain consistency across documentation.Let's verify the usage of these components:
✅ Verification successful
Verified: Component usage confirmed
The
DocContributionNotesandTalkToMecomponents are correctly utilized withinmarkdown/blog/2023-Q4-docs-report.md, ensuring consistency and reusability across the documentation.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Verify the usage of imported components rg --type md '<DocContributionNotes' markdown/blog/2023-Q4-docs-report.md rg --type md '<TalkToMe' markdown/blog/2023-Q4-docs-report.mdLength of output: 177
markdown/blog/2023-April-docs-report.md (5)
16-17: LGTM! Import statements align with PR objectives.The addition of these import statements for
DocContributionNotesandTalkToMecomponents is in line with the PR's goal of replacing duplicated content with reusable fragments. This change contributes to improving maintainability and adhering to the DRY principle.
84-84: LGTM! Improved visual consistency in mermaid diagram.The addition of the style declaration for node D enhances the visual consistency of the mermaid diagram. This change ensures that all nodes in the diagram have a consistent appearance.
115-116: LGTM! Replaced duplicated content with reusable component.The replacement of the contribution information with the
DocContributionNotescomponent aligns perfectly with the PR's objective of reducing duplication and improving maintainability. This change ensures consistency in how contribution information is presented across the documentation.
119-119: LGTM! Replaced duplicated content with reusable component.The replacement of the "Talk to me" section content with the
TalkToMecomponent is in line with the PR's goal of reducing duplication and improving maintainability. This change ensures consistency in how contact information is presented across the documentation.
Line range hint
1-119: Summary: Changes successfully implement PR objectives.The modifications in this file effectively implement the PR's goal of replacing duplicated content with reusable fragments. The addition of import statements and the use of
DocContributionNotesandTalkToMecomponents contribute to improved maintainability and consistency across the documentation. These changes align well with the DRY principle and the overall objectives outlined in the PR summary and linked issues.markdown/blog/2023-june-docs-report.md (5)
16-17: LGTM: Reusable fragments importedThe addition of these imports aligns well with the PR objective of replacing duplicated content with reusable fragments. This change promotes the DRY principle and establishes a single source of truth for contribution notes and contact information.
112-118: LGTM: Mermaid diagram styles enhancedThe additional style definitions for the mermaid diagram enhance its visual appeal and maintain consistency with the existing style. This improvement contributes to a better overall presentation of the AsyncAPI Docs' June Summary.
126-127: LGTM: Reusable DocContributionNotes component usedThe use of the DocContributionNotes component effectively replaces duplicated content with a reusable fragment. This change directly addresses the PR objective, promoting consistency across the documentation and reducing maintenance overhead.
130-130: LGTM: Reusable TalkToMe component usedThe use of the TalkToMe component effectively replaces duplicated content with a reusable fragment. This change directly addresses the PR objective, promoting consistency across the documentation and reducing maintenance overhead.
16-17: Verify the usage of reusable componentsThe introduction of reusable components (DocContributionNotes and TalkToMe) is a positive change. To ensure consistency and correct implementation across the codebase:
Run the following script to check the usage of these components in other files:
This will help ensure that the components are used consistently across the documentation.
Also applies to: 126-127, 130-130
markdown/blog/2023-Q1-docs-report.md (3)
17-18: LGTM: New component imports enhance document reusability.The addition of
DocContributionNotesandTalkToMecomponents aligns well with the PR objective of replacing duplicated content with reusable fragments. This approach improves maintainability and consistency across the documentation.
176-177: LGTM: Added reusable DocContributionNotes component.The addition of the
DocContributionNotescomponent aligns perfectly with the PR objective of replacing duplicated content with reusable fragments. This approach improves maintainability and ensures consistency across the documentation. It's a great way to provide information about contributing to AsyncAPI docs without duplicating content.
Line range hint
1-180: Overall, excellent changes that align with PR objectives.The modifications in this file, particularly the addition of reusable components (
DocContributionNotesandTalkToMe), align well with the PR objective of replacing duplicated content with reusable fragments. These changes will significantly improve maintainability and consistency across the AsyncAPI documentation.The updates to the content, such as the GSoD 2023 information and application count, keep the document current and relevant. However, consider the suggestions for future-proofing this information to reduce the need for frequent updates.
The minor formatting adjustments, while beneficial, could be handled by linters in the future to ensure consistency and reduce manual work.
Great job on improving the documentation structure and content!
markdown/blog/google-season-of-docs-2022.md (4)
17-18: LGTM: New import statement for reusable fragmentThe addition of the import statement for
DocContributionNotesaligns well with the PR objective of replacing duplicated content with reusable fragments. This change promotes code reuse and maintainability.
19-19: LGTM: Improved document structureMoving the heading "¡Hola, AsyncAPI community!" after the import statement improves the overall structure of the document. This change maintains a logical flow from imports to content.
94-94: Excellent use of reusable fragment for contribution notesThe replacement of the previous bullet points with the
DocContributionNotescomponent is an excellent implementation of the PR objective. This change:
- Reduces content duplication across documents
- Improves maintainability by centralizing contribution notes
- Ensures consistency in contribution information across the project
Great job on implementing this reusable fragment!
Line range hint
1-95: Overall assessment: Changes align well with PR objectivesThe modifications in this file successfully implement the PR objective of replacing duplicated content with reusable fragments, particularly with the introduction of the
DocContributionNotescomponent. The changes improve document structure and maintainability.A minor formatting issue with hard tabs was identified and should be addressed. Once this is resolved, the changes are ready for approval.
Great work on improving the documentation structure and reducing duplication!
🧰 Tools
🪛 Markdownlint
78-78: Column: 21
Hard tabs(MD010, no-hard-tabs)
80-80: Column: 16
Hard tabs(MD010, no-hard-tabs)
96-96: null
Emphasis used instead of a heading(MD036, no-emphasis-as-heading)
README.md (5)
59-59: LGTM: Improved formattingThe spacing adjustment in the installation step enhances readability.
127-127: Correct syntax in Docker build commandThe removal of the extra backtick fixes the code block syntax, ensuring proper rendering of the Docker build command.
Line range hint
233-245: LGTM: Improved flowchart formattingThe formatting adjustments to the Netlify Edge Function flowchart explanation enhance readability and maintain consistency with the rest of the document.
258-258: LGTM: Minor formatting adjustmentThe small formatting change in the project structure section maintains consistency with the rest of the document.
Line range hint
1-1: Overall: Excellent improvements to the READMEThe changes in this file effectively address the PR objectives by introducing instructions for using shared Markdown fragments. This addition, along with various formatting improvements, enhances the overall quality and maintainability of the documentation. The new feature for content reuse will help reduce duplication and improve consistency across the AsyncAPI website repository.
markdown/docs/tools/index.md
Outdated
| ## Tools: the AsyncAPI tools ecosystem | ||
|
|
||
| Welcome to AsyncAPI **Tools**! Our Tools section documents the AsyncAPI tools ecosystem. | ||
|
|
||
| <Remember> | ||
|
|
||
| ## Contribute to AsyncAPI Tools | ||
| <DocContributionNotes /> |
There was a problem hiding this comment.
💡 Codebase verification
Issue Found: DocContributionNotes component file is missing.
The DocContributionNotes component referenced in markdown/docs/tools/index.md does not exist at the specified path assets/docs/fragments/contribution-notes.md. This could lead to broken documentation sections.
- Missing File:
assets/docs/fragments/contribution-notes.md
Please verify the correct location of the DocContributionNotes component or ensure that the file is added to the repository.
🔗 Analysis chain
LGTM! Verify content of the new component.
The use of <DocContributionNotes /> effectively replaces the previously detailed contribution steps, aligning with the PR objective of reducing duplication and improving maintainability.
Please ensure that the DocContributionNotes component includes all necessary information previously present in this section, such as links to the Contribution Guide, Code of Conduct, and AsyncAPI Docs Board. Run the following script to verify the content:
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Verify the content of the DocContributionNotes component
# Test: Check if the component file exists and contains necessary information
cat @/assets/docs/fragments/contribution-notes.md | grep -E "Contribution Guide|Code of Conduct|AsyncAPI Docs Board"
# Test: Ensure the component is used consistently across documentation
rg --type md '<DocContributionNotes />'
Length of output: 1195
| Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️ | ||
|
|
There was a problem hiding this comment.
Great introduction, minor grammatical fix needed.
The introduction effectively emphasizes the importance of documentation contributions. However, there's a minor grammatical issue to address.
Please apply the following change:
-Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️
+Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefits the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️This change ensures subject-verb agreement between "help" and "benefits".
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️ | |
| Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefits the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️ | |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~1-~1: This verb does not appear to agree with the subject. Consider using a different form.
Context: ... OSS; Dev Docs are a huge help that benefit the entire OSS ecosystem. At AsyncAPI, ...(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)
There was a problem hiding this comment.
Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!
| - **May:** Orientation on how to contribute to AsyncAPI Inititiave, how Docs issues are organized, detail how we're migrating our CLI and Tools Docs, and assign good `first-time-tickets` to get each new TW contributor started. | ||
| - **June - August:** Each TW goes through designated issues marked for both first time contributors and work set aside for `GSoD 2022`. Each TW starts creating documentation for their individual issues assigned/selected. |
There was a problem hiding this comment.
Minor content changes approved, but please address formatting
The content changes in the timeline section are minor and maintain the original meaning. However, there's a formatting issue to address:
Please replace the hard tabs with spaces on lines 77, 78, and 80 to maintain consistency with the rest of the document and prevent potential formatting issues.
Also applies to: 80-80
🧰 Tools
🪛 Markdownlint
78-78: Column: 21
Hard tabs(MD010, no-hard-tabs)
@derberg thanks for your feedback. At first, I didn't spot this location and decided to put fragments closer to docs, so, thank you for pointing me in the right direction. MDX was chosen only to ensure that importing will work properly during the build process. It appears that the import works for plain Markdown files as well, Next.js does its dirty magic :) I updated the PR according to your suggestions, please have a look. P.S: Done ✅ |
bandantonio
force-pushed
the
docs/deduplicate-content-with-fragments
branch
from
ef61853
to
4f100e6
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (10)
markdown/docs/reference/index.md (3)
6-6: LGTM! Consider using named import for clarity.The import statement is correctly placed and uses the appropriate path. Good job on implementing the reusable fragment as discussed in the PR objectives.
For improved clarity, consider using a named import:
-import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md'; +import { ContributionNotes } from '@/assets/docs/fragments/contribution-notes.md';This change would make it explicit that we're importing a named export from the module, which is a common pattern in JavaScript/TypeScript projects.
15-15: LGTM! Consider adding a brief introduction.The use of the ContributionNotes component effectively replaces the duplicated content, aligning with the PR objectives. This change will improve maintainability and ensure consistency across the documentation.
To maintain consistency with the previous version and provide context, consider adding a brief introduction before the component:
## Contribute to the AsyncAPI Reference section + +We welcome contributions to improve the AsyncAPI Reference. Here's how you can contribute: + <ContributionNotes />This addition would provide a smooth transition to the reusable content and maintain the welcoming tone of the original text.
Line range hint
1-15: Great job implementing reusable fragments!This change successfully addresses the main objective of the PR by replacing duplicated content with a reusable fragment. The implementation is clean and effective, which will significantly improve the maintainability of the documentation.
A few points to consider:
- The use of the ContributionNotes component aligns well with the DRY principle mentioned in issue [📑 Docs]: Deduplicate content and replace it with reusable fragments #3261.
- This change contributes to creating a single source of truth for contribution guidelines.
- The MDX-like syntax used here (importing and using components in Markdown) is appropriate and works well with Next.js, as mentioned in the PR comments.
Overall, this is a solid improvement to the documentation structure. Great work!
As you continue this refactoring process, consider conducting an audit of the documentation to identify other opportunities for creating reusable fragments, as suggested in issue #3261. This will further enhance the consistency and maintainability of the documentation.
markdown/docs/tutorials/index.md (2)
6-6: LGTM! Consider using .mdx extension for clarity.The import statement is correct and aligns with the PR objective of using reusable fragments.
While the
.mdextension works due to Next.js support, consider using the.mdxextension for the imported file to explicitly indicate that it contains JSX-like syntax:-import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md'; +import ContributionNotes from '@/assets/docs/fragments/contribution-notes.mdx';This change would make it clearer that the file contains a reusable component.
Line range hint
6-16: Great job implementing reusable fragments!The changes in this file effectively implement the use of a reusable component for contribution notes, which aligns perfectly with the PR objectives and the DRY principle mentioned in issue #3261. This approach will significantly improve maintainability and consistency across the documentation.
To further improve the documentation structure:
- Consider creating a dedicated directory for reusable fragments if not already present.
- Document the usage of these fragments in the project's contribution guidelines to ensure other contributors can easily adopt this pattern.
markdown/docs/community/index.md (3)
15-15: LGTM: Reusable component for contribution notes.The
<ContributionNotes />component is correctly implemented, replacing the detailed contribution section with a reusable fragment. This change aligns well with the PR objective and should improve maintainability.Consider adding a brief introductory sentence before the component to provide context, such as:
Here's how you can contribute to the AsyncAPI Community: <ContributionNotes />This addition would help set the context for the content provided by the reusable component.
8-8: Remove trailing period from heading.To adhere to Markdown best practices and resolve the linter warning, please remove the trailing period from the heading.
Apply this change:
-## Community: Guidelines and resources around community. +## Community: Guidelines and resources around community🧰 Tools
🪛 Markdownlint
8-8: Punctuation: '.'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
Line range hint
1-15: Overall improvement in documentation structure.The changes in this file successfully implement the use of reusable fragments for contribution notes, aligning with the PR objectives and improving maintainability. The file structure is now simpler and adheres to the DRY principle.
To fully leverage this improvement:
- Ensure that all other files using the contribution notes are updated similarly.
- Consider updating the documentation to explain how to use and maintain these reusable fragments, as mentioned in the PR objectives.
This will help maintain consistency across the documentation and guide future contributors on using the new structure.
🧰 Tools
🪛 Markdownlint
8-8: Punctuation: '.'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
markdown/blog/google-season-of-docs-2022.md (1)
94-94: LGTM: Duplicated content replaced with reusable component.The replacement of the contribution section with the
ContributionNotescomponent aligns well with the PR objective and improves maintainability.Consider adjusting the introductory text to flow better with the imported content. For example:
-Last but not least, don't forget that <ContributionNotes /> +Last but not least, here's how you can contribute: <ContributionNotes />This change would provide a smoother transition to the imported content.
README.md (1)
138-153: Great addition: Instructions for using shared Markdown fragments.This new section provides clear instructions on how to use shared Markdown fragments, which aligns perfectly with the PR objective of reducing duplication in the documentation. This will help contributors maintain consistency and adhere to the DRY principle.
A minor suggestion to enhance this section:
Consider adding a brief explanation of the benefits of using shared fragments, such as improved maintainability and consistency across documentation. This could help reinforce the importance of this practice to contributors.
Example:
## Use shared Markdown fragments +Using shared Markdown fragments helps reduce duplication, improve maintainability, and ensure consistency across our documentation. By centralizing common content, we can easily update information in one place and have it reflected everywhere it's used. + To minimize the duplication of content and make it easier to maintain, there are shared fragments you can use when working with Markdown files. These fragments are stored in the `/assets/docs/fragments` directory.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (21)
- README.md (1 hunks)
- assets/docs/fragments/contribution-notes.md (1 hunks)
- assets/docs/fragments/how-to-contribute.md (1 hunks)
- assets/docs/fragments/talk-to-me.md (1 hunks)
- markdown/blog/2023-April-docs-report.md (2 hunks)
- markdown/blog/2023-Q1-docs-report.md (2 hunks)
- markdown/blog/2023-Q4-docs-report.md (2 hunks)
- markdown/blog/2023-july-docs-report.md (2 hunks)
- markdown/blog/2023-june-docs-report.md (2 hunks)
- markdown/blog/2023-may-docs-report.md (2 hunks)
- markdown/blog/changes-coming-docs.md (2 hunks)
- markdown/blog/google-season-of-docs-2022.md (2 hunks)
- markdown/docs/community/index.md (1 hunks)
- markdown/docs/concepts/asyncapi-document/adding-bindings.md (1 hunks)
- markdown/docs/concepts/index.md (1 hunks)
- markdown/docs/guides/index.md (1 hunks)
- markdown/docs/reference/bindings/index.md (1 hunks)
- markdown/docs/reference/index.md (1 hunks)
- markdown/docs/tools/index.md (1 hunks)
- markdown/docs/tutorials/generate-code.md (1 hunks)
- markdown/docs/tutorials/index.md (2 hunks)
🚧 Files skipped from review as they are similar to previous changes (13)
- assets/docs/fragments/how-to-contribute.md
- assets/docs/fragments/talk-to-me.md
- markdown/blog/2023-April-docs-report.md
- markdown/blog/2023-Q1-docs-report.md
- markdown/blog/2023-Q4-docs-report.md
- markdown/blog/2023-july-docs-report.md
- markdown/blog/2023-june-docs-report.md
- markdown/blog/2023-may-docs-report.md
- markdown/docs/concepts/asyncapi-document/adding-bindings.md
- markdown/docs/concepts/index.md
- markdown/docs/guides/index.md
- markdown/docs/reference/bindings/index.md
- markdown/docs/tutorials/generate-code.md
🧰 Additional context used
🪛 LanguageTool
assets/docs/fragments/contribution-notes.md
[uncategorized] ~1-~1: This verb does not appear to agree with the subject. Consider using a different form.
Context: ... OSS; Dev Docs are a huge help that benefit the entire OSS ecosystem. At AsyncAPI, ...(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)
[uncategorized] ~12-~12: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ave a documentation contributor question and you're wondering how to tag me into a G...(COMMA_COMPOUND_SENTENCE)
🪛 Markdownlint
markdown/docs/community/index.md
8-8: Punctuation: '.'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
🔇 Additional comments (18)
markdown/docs/community/index.md (1)
6-6: LGTM: Import statement for reusable fragment.The import statement for
ContributionNotesis correctly implemented and aligns with the PR objective of using reusable fragments to reduce duplication.To ensure the import path is correct, please run the following script:
✅ Verification successful
Verified: Import path exists as expected.
The import statement for
ContributionNoteshas been successfully verified and the file exists atassets/docs/fragments/contribution-notes.md.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Verify the existence of the imported file fd -t f "contribution-notes.md" assets/docs/fragmentsLength of output: 97
markdown/docs/tools/index.md (2)
15-15: LGTM! Ensure all necessary information is included in the ContributionNotes component.The use of
<ContributionNotes />effectively replaces the previously detailed contribution steps, aligning with the PR objective of reducing duplication and improving maintainability.Please ensure that the
ContributionNotescomponent includes all necessary information previously present in this section, such as links to the Contribution Guide, Code of Conduct, and AsyncAPI Docs Board. The verification script in the previous comment will help confirm this.
6-6: Verify the existence and contents of the imported file.The import statement aligns with the PR objective of using reusable fragments. However, we need to ensure that the file exists and contains the necessary information.
Run the following script to verify the file's existence and contents:
✅ Verification successful
Verification Successful: The
contribution-notes.mdfile exists and contains the required information.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Verify the existence and contents of the ContributionNotes component # Test: Check if the file exists if [ -f "assets/docs/fragments/contribution-notes.md" ]; then echo "File exists." # Test: Check if the file contains necessary information grep -E "Contribution Guide|Code of Conduct|AsyncAPI Docs Board" assets/docs/fragments/contribution-notes.md else echo "File does not exist." fiLength of output: 517
assets/docs/fragments/contribution-notes.md (4)
1-2: Fix grammatical issue in the introductionThe introduction effectively emphasizes the importance of documentation contributions. However, there's a minor grammatical issue that needs to be addressed.
Please apply the following change:
-Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️ +Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefits the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️This change ensures subject-verb agreement between "help" and "benefits".
🧰 Tools
🪛 LanguageTool
[uncategorized] ~1-~1: This verb does not appear to agree with the subject. Consider using a different form.
Context: ... OSS; Dev Docs are a huge help that benefit the entire OSS ecosystem. At AsyncAPI, ...(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)
3-8: Well-structured guide for new contributorsThe steps provided offer a clear and concise guide for new documentation contributors. The inclusion of links to the Contribution Guide, Code of Conduct, and AsyncAPI Docs Board is particularly helpful. The encouragement to engage through comments and questions promotes a welcoming environment for new contributors.
1-14: Excellent addition of reusable contribution notesThis new file successfully achieves the PR objective of creating reusable fragments for contribution notes. It effectively addresses the need to deduplicate content across documentation files, as mentioned in issue #3261. The content is well-structured, informative, and encourages new contributors to get involved in the documentation process.
The update of the GitHub handle to 'alequetzalli' also resolves issue #3185, ensuring that all references are current and accurate.
Great job on improving the documentation structure and maintainability!
🧰 Tools
🪛 LanguageTool
[uncategorized] ~1-~1: This verb does not appear to agree with the subject. Consider using a different form.
Context: ... OSS; Dev Docs are a huge help that benefit the entire OSS ecosystem. At AsyncAPI, ...(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)
[uncategorized] ~12-~12: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ave a documentation contributor question and you're wondering how to tag me into a G...(COMMA_COMPOUND_SENTENCE)
12-14: Clear instructions and updated GitHub handleThe instructions for tagging a specific contributor are clear and helpful. The update of the GitHub handle to 'alequetzalli' successfully addresses the objective mentioned in issue #3185.
To ensure the GitHub handle has been consistently updated throughout the repository, please run the following script:
This script will help identify any instances of the old handle that might have been missed in other files.
✅ Verification successful
GitHub handle consistently updated
All instances of the GitHub handle have been successfully updated to
alequetzalliacross the repository.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Verify that the GitHub handle has been updated consistently # Test: Search for any remaining instances of the old handle rg --type md "alequetzalli" -g '!assets/docs/fragments/contribution-notes.md'Length of output: 5362
🧰 Tools
🪛 LanguageTool
[uncategorized] ~12-~12: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ave a documentation contributor question and you're wondering how to tag me into a G...(COMMA_COMPOUND_SENTENCE)
markdown/blog/changes-coming-docs.md (5)
17-18: Great addition of reusable fragments!The introduction of
ContributionNotesandTalkToMecomponents aligns perfectly with the PR objective of replacing duplicated content with reusable fragments. This approach will help maintain consistency across documentation and improve maintainability.
Line range hint
19-127: Main content remains consistent with PR objectivesThe main body of the blog post continues to effectively communicate the planned changes to the AsyncAPI documentation structure. This content aligns well with the PR objectives by explaining the rationale behind the new documentation organization.
128-129: Excellent use of the ContributionNotes componentThe integration of the
ContributionNotescomponent here is a great example of using reusable fragments to maintain consistent contribution information across the documentation. This aligns perfectly with the PR objectives and will help reduce duplication.
131-132: Great implementation of the TalkToMe componentThe use of the
TalkToMecomponent as a concluding section is an excellent way to maintain a consistent call-to-action across different parts of the documentation. This aligns well with the PR objectives and enhances community engagement.
Line range hint
1-132: Overall, excellent implementation of reusable fragmentsThe changes made to this file successfully achieve the PR objectives by introducing reusable fragments (
ContributionNotesandTalkToMe) while maintaining the integrity of the original content. This approach will significantly improve consistency across the documentation and reduce duplication. Great work!markdown/blog/google-season-of-docs-2022.md (3)
17-18: LGTM: Import statement for reusable component added.The import statement for
ContributionNoteshas been correctly added, aligning with the PR objective of replacing duplicated content with reusable fragments. The empty line after the import improves readability.
Line range hint
1-95: Overall changes align well with PR objectives.The modifications to this file are minimal and focused, successfully implementing the use of reusable fragments for duplicated content. The overall structure and content of the blog post have been preserved, maintaining its original intent and information.
The changes made contribute to:
- Reducing duplication in the documentation
- Improving maintainability
- Establishing a single source of truth for contribution guidelines
These outcomes align perfectly with the PR objectives and the linked issue #3261.
🧰 Tools
🪛 LanguageTool
[style] ~20-~20: ‘Any and all’ might be wordy. Consider a shorter alternative.
Context: ...inGoogle Season of Docs 2022 (GSoD). Any and all technical writers are welcome to come p...(EN_WORDINESS_PREMIUM_ANY_AND_ALL)
Line range hint
1-95: Past formatting issues resolved.The formatting issues mentioned in the previous review comment, specifically the use of hard tabs on lines 77, 78, and 80, have been addressed. The file now consistently uses spaces for indentation, improving overall formatting consistency.
🧰 Tools
🪛 LanguageTool
[style] ~20-~20: ‘Any and all’ might be wordy. Consider a shorter alternative.
Context: ...inGoogle Season of Docs 2022 (GSoD). Any and all technical writers are welcome to come p...(EN_WORDINESS_PREMIUM_ANY_AND_ALL)
README.md (3)
137-137: LGTM: Docker build command formatting fixed.The backtick in the Docker build command has been correctly formatted, improving the readability of the README.
Line range hint
154-354: Contributors list updated.The list of contributors has been automatically updated to include new contributors. This is a positive change that acknowledges the growing community involvement in the project.
🧰 Tools
🪛 LanguageTool
[style] ~135-~135: Consider shortening or rephrasing this to strengthen your wording.
Context: ...local copy of the website. Whenever you make changes to the code, the website will refresh and ...(MAKE_CHANGES)
🪛 Markdownlint
157-157: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
Line range hint
1-354: Overall improvements to README clarity and maintainability.The changes to this README file are well-aligned with the PR objectives:
- The new section on using shared Markdown fragments directly addresses the goal of reducing duplicated content and improving maintainability.
- Minor corrections and updates enhance the overall clarity of the document.
- The updated contributors list reflects the growing community involvement.
These changes will help contributors better understand how to work with the project's documentation and encourage the use of reusable components, which is a significant step towards more maintainable and consistent documentation.
🧰 Tools
🪛 LanguageTool
[style] ~135-~135: Consider shortening or rephrasing this to strengthen your wording.
Context: ...local copy of the website. Whenever you make changes to the code, the website will refresh and ...(MAKE_CHANGES)
🪛 Markdownlint
157-157: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
|
|
||
| ### Docs contributor questions | ||
| Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear! | ||
| <ContributionNotes /> |
| 1. Import the fragment at the top of the file (but below the frontmatter) using the following syntax: | ||
|
|
||
| ```md | ||
| import DesiredFragmentName from '@/assets/docs/fragments/fragmentYouWantToImport.md'; |
There was a problem hiding this comment.
great stuff with @ instead of super complex ../../../ paths!
There was a problem hiding this comment.
tsconfig.json has proper configuration for aliases, idk why this feature hasn't been used here :)
| Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️ | ||
|
|
@derberg If you're talking about this comment, there are valid suggestions, but some of them seem redundant. For example, |
|
@bandantonio no no, I meant the inline comment, some grammar suggestion from code rabbit - but it ain't there anymore |
|
/rtm |
Description
Related issue(s)
Resolves #3261
Should be merged together with #3270
Closes #3185 as no longer relevant
Summary by CodeRabbit
New Features
ContributionNotesandTalkToMeto enhance community engagement and contribution guidance across various documentation files.Bug Fixes
Documentation