docs: expand community docs: contributor - recommended tools #1777
Conversation
ezinneanne
requested review from
quetzalliwrites,
derberg,
asyncapi-bot-eve and
thulieblack
as code owners
|
Hi @bandantonio @thulieblack , I have separated my previous PR #1730 and I added the recommended tools document in this PR. Kindly review |
recommended_tools.md
Outdated
| # Contributor - Recommended Tools | ||
| This article covers the recommended tools you should have as a contributor. With these tools, you can set up workflows and begin making contributions. | ||
|
|
||
| These are the recommended tools you need:- |
There was a problem hiding this comment.
| These are the recommended tools you need:- | |
| These are the recommended tools: |
recommended_tools.md
Outdated
| - A laptop or a desktop computer capable of running tools which you would use for contribution. | ||
| - A stable internet connection to fork, clone a repo, make changes, and submit a PR. |
There was a problem hiding this comment.
These are partially true.
Both of these are important prerequisites for sure but they are already met when accessing and reading this document.
A stable internet connection to fork, clone a repo, make changes, and submit a PR.
You need an Internet connection (not necessarily a stable one) to fork, clone, and submit a PR, but you can work offline with git while making your changes. This is one of the greatest benefits of git compared to svn, for example.
recommended_tools.md
Outdated
| These are the recommended tools you need:- | ||
| - A laptop or a desktop computer capable of running tools which you would use for contribution. | ||
| - A stable internet connection to fork, clone a repo, make changes, and submit a PR. | ||
| - Install [Git](https://git-scm.com)- a version control system. |
There was a problem hiding this comment.
| - Install [Git](https://git-scm.com)- a version control system. | |
| - [Git](https://git-scm.com) to work with the organization's repositories. |
recommended_tools.md
Outdated
| - A laptop or a desktop computer capable of running tools which you would use for contribution. | ||
| - A stable internet connection to fork, clone a repo, make changes, and submit a PR. | ||
| - Install [Git](https://git-scm.com)- a version control system. | ||
| - [A GitHub account](https://github.com). AsyncAPI hosts all its project source code and dependencies on GitHub. You'll need a GitHub account to create issues, fork the repository, submit pull requests, and more. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). |
There was a problem hiding this comment.
General recommendation: please be consistent with wording - I see differences in the following cases:
- PR vs pull request
- repo vs repository
- VSCode vs VS Code (the last one is correct)
recommended_tools.md
Outdated
| - A stable internet connection to fork, clone a repo, make changes, and submit a PR. | ||
| - Install [Git](https://git-scm.com)- a version control system. | ||
| - [A GitHub account](https://github.com). AsyncAPI hosts all its project source code and dependencies on GitHub. You'll need a GitHub account to create issues, fork the repository, submit pull requests, and more. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). | ||
| - A code editor, such as [VS Code](https://code.visualstudio.com). |
There was a problem hiding this comment.
| - A code editor, such as [VS Code](https://code.visualstudio.com). | |
| - A code editor, such as [VS Code](https://code.visualstudio.com) to work on your changes. |
recommended_tools.md
Outdated
| - Install [Git](https://git-scm.com)- a version control system. | ||
| - [A GitHub account](https://github.com). AsyncAPI hosts all its project source code and dependencies on GitHub. You'll need a GitHub account to create issues, fork the repository, submit pull requests, and more. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). | ||
| - A code editor, such as [VS Code](https://code.visualstudio.com). | ||
| - [Nodejs and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). So you can run the website locally on your machine. |
There was a problem hiding this comment.
| - [Nodejs and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). So you can run the website locally on your machine. | |
| - [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to build and run the website locally. |
recommended_tools.md
Outdated
| - [A GitHub account](https://github.com). AsyncAPI hosts all its project source code and dependencies on GitHub. You'll need a GitHub account to create issues, fork the repository, submit pull requests, and more. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). | ||
| - A code editor, such as [VS Code](https://code.visualstudio.com). | ||
| - [Nodejs and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). So you can run the website locally on your machine. | ||
| - A working browser such as Google Chrome, Firefox or Microsoft Edge where you can preview your changes. |
There was a problem hiding this comment.
| - A working browser such as Google Chrome, Firefox or Microsoft Edge where you can preview your changes. | |
| - A web browser, such as Google Chrome, Firefox or Microsoft Edge to preview your changes. |
recommended_tools.md
Outdated
| - A code editor, such as [VS Code](https://code.visualstudio.com). | ||
| - [Nodejs and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). So you can run the website locally on your machine. | ||
| - A working browser such as Google Chrome, Firefox or Microsoft Edge where you can preview your changes. | ||
| - Lastly, you need a command line terminal where you can run commands. You can use your local command line or the terminal in VSCode. |
There was a problem hiding this comment.
I would place it right after the code editor and before Node.js
| - Lastly, you need a command line terminal where you can run commands. You can use your local command line or the terminal in VSCode. | |
| - Command-line terminal, such as the one included in your OS, or the terminal integrated in your code editor or IDE, to run commands. |
recommended_tools.md
Outdated
| - [A GitHub account](https://github.com). AsyncAPI hosts all its project source code and dependencies on GitHub. You'll need a GitHub account to create issues, fork the repository, submit pull requests, and more. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). | ||
| - A code editor, such as [VS Code](https://code.visualstudio.com). | ||
| - [Nodejs and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). So you can run the website locally on your machine. | ||
| - A working browser such as Google Chrome, Firefox or Microsoft Edge where you can preview your changes. |
There was a problem hiding this comment.
What about previewing Markdown documents that do not require spinning up a website and/or opening a browser?
|
@bandantonio I have made the requested changes, kindly review. |
|
@ezinneanne Have you considered enhancing and expanding the existing document community/docs/onboarding-guide/tools-and-setup instead of creating a new one? |
Great idea! I would have to expand the existing document then |
|
But that one is specific for tech writers unless we create a docs for all? |
|
I feel a general setup would be best @bandantonio @thulieblack |
| - Command-line terminal, such as the one included in your OS, or the terminal integrated in your code editor or IDE, to run commands. | ||
| - [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to build and run the website locally. | ||
| - A web browser, such as Google Chrome, Firefox or Microsoft Edge to preview your changes. | ||
| - Markdown All-In-One VS Code extension to preview markdown documents. |
There was a problem hiding this comment.
This line contradicts with a free choice of code editor (line 13).
Furthermore, VS Code has powerful out-of-the-box capabilities to work with Markdown documents, including preview., no extension needed. So, I would just mention something like "To preview minor changes in Markdown documents without spinning up a dev server, you can use out-of-the-box capabilities of your code editor, or install the corresponding extension. For more information, please consult your code editor's documentation."
|
@thulieblack @bandantonio I have made the requested changes. Since, we are using a general setup, should I delete the |
|
Honestly, I don't really have an opinion here. Or maybe actually follow Anton's suggestion here #1777 (comment) |
@ezinneanne My proposal was to expand the existing document ( |
| This article covers the recommended tools you should have as a contributor. With these tools, you can set up workflows and begin making contributions. | ||
|
|
||
| These are the recommended tools:- |
There was a problem hiding this comment.
| This article covers the recommended tools you should have as a contributor. With these tools, you can set up workflows and begin making contributions. | |
| These are the recommended tools:- |
| - [Git](https://git-scm.com)- to work with the organization's repositories. | ||
| - [A GitHub account](https://github.com). AsyncAPI hosts all its project source code and dependencies on GitHub. You'll need a GitHub account to create issues, fork the repository, submit pull requests, and more. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). | ||
| - A code editor, such as [VS Code](https://code.visualstudio.com) to work on your changes. | ||
| - Command-line terminal, such as the one included in your OS, or the terminal integrated in your code editor or IDE, to run commands. | ||
| - [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to build and run the website locally. | ||
| - A web browser, such as Google Chrome, Firefox or Microsoft Edge to preview your changes. | ||
| - To preview minor changes in Markdown documents without spinning up a dev server, you can use out-of-the-box capabilities of your code editor, or install the corresponding extension. For more information, please consult your code editor's documentation. |
There was a problem hiding this comment.
Please double check my previous suggestions on updated formatting of this list. I don't see them implemented.
There was a problem hiding this comment.
am sorry, I checked previous suggestions but I can't find the one on formatting of lists. Can you please guide me to it?
There was a problem hiding this comment.
Don't worry, just a few of them. I left a few comments with explanations. Please have a look.
WalkthroughThe onboarding guide documentation was updated to provide a more comprehensive and detailed list of recommended tools and setup instructions for contributors. The section previously focused on basic hardware and software requirements for technical writers, but now outlines specific tools such as Git, a GitHub account, a code editor, a terminal, Node.js, npm, and a web browser. Additional instructions were included for previewing Markdown changes without running a development server. The document title and introductory sentence were also revised to reflect these expanded recommendations. Changes
Poem
Tip ⚡💬 Agentic Chat (Pro Plan, General Availability)
🪧 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: 0
♻️ Duplicate comments (1)
docs/onboarding-guide/recommended_tools.md (1)
13-13: 🛠️ Refactor suggestionCode Editor Recommendation Neutrality
The phrase "
A code editor, such as [VS Code]" may imply a default recommendation rather than emphasizing free choice. Rewording it to underscore that contributors are free to choose their editor would avoid any potential misinterpretation.- - A code editor, such as [VS Code](https://code.visualstudio.com) to work on your changes. + - A code editor of your choice, e.g. [VS Code](https://code.visualstudio.com), to work on your changes.
🧹 Nitpick comments (3)
docs/onboarding-guide/recommended_tools.md (3)
7-7: Heading Consideration: Duplication AlertThe header "
# Contributor - Recommended Tools" is clear; however, it duplicates context already provided by the YAML title. Consider simplifying it to "# Recommended Tools" if the inclusion of "Contributor" is redundant.
10-10: List Introduction FormattingThe introduction line "
These are the recommended tools:-" contains an extra dash after the colon. Removing the dash will improve clarity.-These are the recommended tools:- +These are the recommended tools:
11-11: Bullet List SpacingFor the Git tool entry, ensure proper spacing around the hyphen for better readability.
- - [Git](https://git-scm.com)- to work with the organization's repositories. + - [Git](https://git-scm.com) - to work with the organization's repositories.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/recommended_tools.md(1 hunks)
🔇 Additional comments (6)
docs/onboarding-guide/recommended_tools.md (6)
1-4: YAML Header: Proper ConfigurationThe YAML front matter correctly defines the document title and weight for ordering. No issues found here.
12-12: GitHub Account Entry ClarityThe entry for a GitHub account is detailed and helpful. It clearly explains its necessity and even directs new users to learn about GitHub functionalities. No action required.
14-14: Command-line Terminal DescriptionThe description correctly explains the purpose and options for using a command-line terminal. It covers both the default OS terminal and integrated editor terminals.
15-15: Node.js and npm EntryThis entry is succinct and provides the correct documentation link. It clearly communicates the requirement for local development.
16-16: Web Browser RecommendationThe web browser entry offers clear choices among popular browsers, which is appropriate for previewing changes.
17-17: Markdown Preview GuidanceThe guidance for previewing minor Markdown changes without a dev server is well-stated. It informs contributors of the capability available in many editors (or via extensions) and directs them to consult their editor’s documentation.
| This article covers the recommended tools you should have as a contributor. With these tools, you can set up workflows and begin making contributions. | ||
|
|
||
| These are the recommended tools:- | ||
| - [Git](https://git-scm.com)- to work with the organization's repositories. |
There was a problem hiding this comment.
Lists must be consistent in formatting/styling. Overall, this list is consistent except for the first two bullets - you have the following format: a tool name at the beginning and description of its purpose - <tool> to <purpose>
Pay attention that this bullet still has an inconsistent dash symbol after the link (which I highlighted in my previous suggestion)
|
|
||
| These are the recommended tools:- | ||
| - [Git](https://git-scm.com)- to work with the organization's repositories. | ||
| - [A GitHub account](https://github.com). AsyncAPI hosts all its project source code and dependencies on GitHub. You'll need a GitHub account to create issues, fork the repository, submit pull requests, and more. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). |
There was a problem hiding this comment.
This bullet is also slightly inconsistent, because it has a full stop after the tool name instead of describing its purpose. At first, I felt that it is ok, since the phrasing is a bit long, so I didn't mention it in suggestions. But now I see that it can be simplified, like this:
| - [A GitHub account](https://github.com). AsyncAPI hosts all its project source code and dependencies on GitHub. You'll need a GitHub account to create issues, fork the repository, submit pull requests, and more. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). | |
| - [A GitHub account](https://github.com) to fork AsyncAPI repositories, create issues, submit pull requests, and participate in discussions. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). |
|
@bandantonio I have made the requested changes, kindly review. |
|
|
||
| Technical writer contributors need the following tools to contribute to AsyncAPI documentation effectively: | ||
| ## Recommended Tools | ||
| These are the recommended tools: |
There was a problem hiding this comment.
This phrase is redundant
|
@bandantonio @thulieblack I have removed the redundant phrase, I await your reviews. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/onboarding-guide/tools-and-setup.md (2)
6-6: Intro sentence improved, but can be more concise.The sentence is clear, but could be streamlined for readability. Consider:
"Below are the recommended tools for contributors and instructions for setting up the AsyncAPI website locally."
8-15: Comprehensive and clear tool recommendations, but minor grammar improvement needed.The list is thorough and well-structured. However, in line 14, add a comma after "Firefox" for correct punctuation:
"...such as Google Chrome, Firefox, or Microsoft Edge..."Apply this diff for the fix:
🧰 Tools
🪛 LanguageTool
[uncategorized] ~14-~14: Possible missing comma found.
Context: ... as Google Chrome, Firefox or Microsoft Edge to preview your changes. - To preview ...(AI_HYDRA_LEO_MISSING_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/tools-and-setup.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/tools-and-setup.md
[uncategorized] ~14-~14: Possible missing comma found.
Context: ... as Google Chrome, Firefox or Microsoft Edge to preview your changes. - To preview ...
(AI_HYDRA_LEO_MISSING_COMMA)
🔇 Additional comments (3)
docs/onboarding-guide/tools-and-setup.md (3)
2-2: Title update is clear and appropriate.Changing the title to "Recommended tools and setup" accurately reflects the expanded scope of the document.
15-15: Excellent tip for Markdown previewing.The advice about previewing Markdown changes without a dev server is helpful and inclusive for various editors.
17-48: Setup instructions are clear and actionable.The step-by-step setup guide is accurate, easy to follow, and covers all necessary steps for new contributors.
🧰 Tools
🪛 LanguageTool
[grammar] ~17-~17: This sentence should probably be started with a verb instead of the noun ‘Setup’. If not, consider inserting a comma for better clarity.
Context: ...t your code editor's documentation. ## Setup your AsyncAPI local environment 1. Fork...(SENT_START_NN_DT)
|
/rtm |
Description
Related issue(s)
See also #1622Summary by CodeRabbit