docs: grammar style guide #1827
Conversation
Signed-off-by: Christine <[email protected]>
Signed-off-by: Christine <[email protected]>
CBID2
requested review from
quetzalliwrites,
derberg,
asyncapi-bot-eve and
thulieblack
as code owners
This reverts commit 242fd1c.
|
Hi @thulieblack! :) I made the pull request and it's ready for a review! 😄 |
|
I don't see the file where is it? |
It's added @thulieblack. |
|
@TRohit20 your review |
WalkthroughA new markdown file has been added to the documentation to serve as the grammar section of the AsyncAPI style guide. The file details guidelines on abbreviations, active voice usage, capitalization, spelling, verb tense, and the use of personal pronouns. It provides examples for each rule and lists additional resources for further reference. Changes
Assessment against linked issues
Suggested labels
Suggested reviewers
Poem
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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: 2
🧹 Nitpick comments (6)
docs/styleguide/grammar.md (6)
12-12: Compound Word Spelling Update.
The term “micro-service” is typically spelled as “microservice” (a single word). Please update this for consistency.🧰 Tools
🪛 LanguageTool
[misspelling] ~12-~12: This word is normally spelled as one.
Context: ...s an example: An application can be a micro-service, IoT (Internet of things) device (for e...(EN_COMPOUNDS_MICRO_SERVICE)
17-17: Markdown Heading Formatting.
Ensure the heading "## Active Voice" starts at the very beginning of the line without any leading spaces to comply with markdown standards.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
17-17: Headings must start at the beginning of the line
null(MD023, heading-start-left)
37-37: Brand Consistency.
Update "Asyncapi's" to "AsyncAPI's" to maintain consistent branding in the document.
38-42: Consistency in Spelling Guidelines.
The spelling guidelines are helpful. Please ensure that the document consistently uses the recommended variants (for example, "organization" instead of "organisation") without mixing different forms elsewhere.🧰 Tools
🪛 LanguageTool
[uncategorized] ~40-~40: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...(EN_WORD_COHERENCY)
50-50: Remove Unnecessary Leading Whitespace.
There is extra whitespace before the text on line 50. Removing this will help maintain clean markdown formatting.
55-55: Markdown Heading Formatting.
Ensure the "## Additional Resources" heading starts at the beginning of the line without any leading spaces.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
55-55: Headings must start at the beginning of the line
null(MD023, heading-start-left)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/styleguide/grammar.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/styleguide/grammar.md
[misspelling] ~12-~12: This word is normally spelled as one.
Context: ...s an example: An application can be a micro-service, IoT (Internet of things) device (for e...
(EN_COMPOUNDS_MICRO_SERVICE)
[uncategorized] ~40-~40: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...
(EN_WORD_COHERENCY)
🪛 markdownlint-cli2 (0.17.2)
docs/styleguide/grammar.md
17-17: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
55-55: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
59-59: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
60-60: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
🔇 Additional comments (3)
docs/styleguide/grammar.md (3)
1-5: YAML Front Matter is Well-Structured.
The YAML front matter correctly sets the title, description, and weight. No changes are required here.
6-6: Document Title Heading.
The primary heading is correctly formatted. Please ensure that "AsyncAPI" is consistently capitalized throughout the document.
43-47: Clear Verb Tense Guidance.
The examples in the Verb Tense section clearly differentiate between present and past tense usage.
docs/styleguide/grammar.md
Outdated
| - [Google Style Guide](https://developers.google.com/style) | ||
| - [Microsoft Style Guide](https://developers.google.com/style) |
There was a problem hiding this comment.
🛠️ Refactor suggestion
List Indentation and Link Issue.
There are two points to address here:
- The unordered list items are indented; please remove any leading spaces so that the dashes start at column zero per markdown standards.
- The Microsoft Style Guide link is currently identical to the Google Style Guide link. Please verify and update the Microsoft Style Guide URL to point to the correct resource.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
59-59: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
60-60: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
docs/styleguide/grammar.md
Outdated
| ✅ **DO:** "In the context of channel addresses within AsyncAPI documents, parameters play a crucial role in defining the dynamic components of an address." | ||
| ❌ **DON'T:** "In the context of channel addresses within AsyncAPI documents, parameters play a crucial role in defining the dynamic components of an address." |
There was a problem hiding this comment.
The two examples are exactly the same. Please iterate here?
Co-authored-by: Rohit <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
docs/styleguide/grammar.md (2)
17-24: 🛠️ Refactor suggestionActive Voice Example Duplication
The DO and DON'T examples in this section are identical, which negates the intended contrast. Please update the DON'T example to use a passive voice. For example:
- DO: "In the context of channel addresses within AsyncAPI documents, parameters play a crucial role in defining the dynamic components of an address."
- DON'T: "Channel addresses within AsyncAPI documents have their dynamic components defined by parameters."
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
17-17: Headings must start at the beginning of the line
null(MD023, heading-start-left)
55-60: 🛠️ Refactor suggestionAdditional Resources: List Formatting & Link Correction
There are two points to address in this section:
- List Indentation: Remove the extra indentation for the unordered list items (lines 59-60) to comply with markdown linting (MD007).
- Link Correction: The Microsoft Style Guide URL on line 60 is identical to the Google Style Guide link. Please update it to the correct Microsoft Style Guide URL. For example:
- - [Microsoft Style Guide](https://developers.google.com/style) + - [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/)🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
55-55: Headings must start at the beginning of the line
null(MD023, heading-start-left)
59-59: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
60-60: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
🧹 Nitpick comments (2)
docs/styleguide/grammar.md (2)
8-15: Nitpick: Update Compound Term Formatting
In the example provided on line 12, consider using “microservice” (as one word) rather than “micro-service” to align with common usage conventions.🧰 Tools
🪛 LanguageTool
[misspelling] ~12-~12: This word is normally spelled as one.
Context: ...s an example: "An application can be a micro-service, IoT (Internet of things) device (for e...(EN_COMPOUNDS_MICRO_SERVICE)
35-42: Consistency in Brand Capitalization
On line 37, update “Asyncapi’s” to “AsyncAPI’s” to maintain consistent branding with the title and other occurrences in the document.🧰 Tools
🪛 LanguageTool
[uncategorized] ~37-~37: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...ling standards. Here are some preferred spelling of certain words: - Use "color" instead...(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
[uncategorized] ~40-~40: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...(EN_WORD_COHERENCY)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/styleguide/grammar.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/styleguide/grammar.md
[misspelling] ~12-~12: This word is normally spelled as one.
Context: ...s an example: "An application can be a micro-service, IoT (Internet of things) device (for e...
(EN_COMPOUNDS_MICRO_SERVICE)
[uncategorized] ~37-~37: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...ling standards. Here are some preferred spelling of certain words: - Use "color" instead...
(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
[uncategorized] ~40-~40: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...
(EN_WORD_COHERENCY)
🪛 markdownlint-cli2 (0.17.2)
docs/styleguide/grammar.md
17-17: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
55-55: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
59-59: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
60-60: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
🔇 Additional comments (4)
docs/styleguide/grammar.md (4)
1-5: Front Matter Formatting Verified
The YAML front matter is correctly formatted and provides the expected metadata.
26-34: Capitalization Section Looks Good
The guidelines for capitalization are clearly outlined. Consider a brief review to ensure punctuation consistency in the rule descriptions if needed.
43-47: Verb Tense Section Is Clear
The examples effectively illustrate the proper use of present tense over past tense.
48-54: Personal Pronouns Guidance Is Well Articulated
The contrast between the DO and DON'T examples is clear, despite the subtle differences. This section meets the objective of guiding proper pronoun usage.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (3)
docs/styleguide/grammar.md (3)
21-22: Update Passive Voice Example in Active Voice Section
Both the DO and DON'T examples in the Active Voice section currently use active voice. To clearly illustrate the intended contrast, please update the DON'T example to use passive voice. For instance:-❌ **DON'T:** "In the context of channel addresses within AsyncAPI documents, parameters played a crucial role in defining the dynamic components of an address." +❌ **DON'T:** "In the context of channel addresses within AsyncAPI documents, the dynamic components of an address were defined by parameters."
52-53: Differentiate the Personal Pronouns Examples
The DON'T example in the Personal Pronouns section (lines 52–53) is nearly identical to the DO example. Removing the extra “can” in the final clause of the DON'T example will clarify the intended contrast.-❌ **DON'T:** "You can add parameters to the `channel.address` by adding a parameter between curly braces like {`braces`}. Next, use `channel.parameters` to define your parameters. Finally, you can leverage the `components.parameters` to enable reusable parameters' definitions across multiple channels." +❌ **DON'T:** "You can add parameters to the `channel.address` by adding a parameter between curly braces like {`braces`}. Next, use `channel.parameters` to define your parameters. Finally, leverage the `components.parameters` to enable reusable parameters' definitions across multiple channels."
55-60: Fix List Indentation and Update Microsoft Style Guide Link
The unordered list items in the Additional Resources section have extra indentation (as flagged by MD007), and the Microsoft Style Guide link duplicates the Google Style Guide link. Please remove the extra indentation and update the Microsoft link to point to the correct URL (for example, Microsoft Style Guide).- - [Google Style Guide](https://developers.google.com/style) - - [Microsoft Style Guide](https://developers.google.com/style) +- [Google Style Guide](https://developers.google.com/style) +- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide)🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
55-55: Headings must start at the beginning of the line
null(MD023, heading-start-left)
59-59: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
60-60: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
🧹 Nitpick comments (3)
docs/styleguide/grammar.md (3)
10-15: Refine Terminology in Abbreviations Section
In the example (lines 12–13), the term “micro-service” is flagged by static analysis. Consider changing it to “microservice” for consistency. Also, updating “Internet of things” to “Internet of Things” will ensure proper noun capitalization.-"An application can be a micro-service, IoT (Internet of things) device (for example, a sensor), mainframe process, and more. - That aspect is particularly beneficial in setups like IoT, where topics are often assigned per device or device segment." +"An application can be a microservice, IoT (Internet of Things) device (for example, a sensor), mainframe process, and more. +That aspect is particularly beneficial in setups like IoT, where topics are often assigned per device or device segment."🧰 Tools
🪛 LanguageTool
[misspelling] ~12-~12: This word is normally spelled as one.
Context: ...s an example: "An application can be a micro-service, IoT (Internet of things) device (for e...(EN_COMPOUNDS_MICRO_SERVICE)
29-33: Minor Formatting Improvement in the Capitalization List
In the bullet under Capitalization (line 32), add a space before the parenthesis for improved readability.-... emphasizing a term or concept(use italics sparingly) +... emphasizing a term or concept (use italics sparingly)
37-37: Enforce Consistent Capitalization for “AsyncAPI”
For consistency with branding, update “Asyncapi's” to “AsyncAPI's” in the Spelling section.-Asyncapi's content and documentation follows American English spelling standards. +AsyncAPI's content and documentation follows American English spelling standards.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/styleguide/grammar.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/styleguide/grammar.md
[misspelling] ~12-~12: This word is normally spelled as one.
Context: ...s an example: "An application can be a micro-service, IoT (Internet of things) device (for e...
(EN_COMPOUNDS_MICRO_SERVICE)
[uncategorized] ~40-~40: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...
(EN_WORD_COHERENCY)
🪛 markdownlint-cli2 (0.17.2)
docs/styleguide/grammar.md
17-17: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
55-55: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
59-59: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
60-60: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
🔇 Additional comments (1)
docs/styleguide/grammar.md (1)
1-6: Front Matter & Header Formatting Looks Good
The YAML front matter and header section (lines 1–6) are correctly formatted and provide the necessary metadata.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
docs/styleguide/grammar.md (2)
21-22: Active Voice Example: Revise the DON'T Example to Use Passive Voice.
The current DON'T example only shifts the tense rather than demonstrating a passive voice construction. Please update it to clearly illustrate a passive voice contrast. For example:-❌ **DON'T:** "In the context of channel addresses within AsyncAPI documents, parameters played a crucial role in defining the dynamic components of an address." +❌ **DON'T:** "Channel addresses in AsyncAPI documents have their dynamic components defined by parameters."
59-60: Markdown List Indentation: Remove Extra Leading Spaces.
The unordered list items in the Additional Resources section are indented, which causes markdownlint warnings. Please remove the extra spaces so that the dashes start at column zero.- - [Google Style Guide](https://developers.google.com/style) - - [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) + - [Google Style Guide](https://developers.google.com/style) + - [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
59-59: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
60-60: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
🧹 Nitpick comments (2)
docs/styleguide/grammar.md (2)
12-13: Spelling Correction: Update "micro-service" to "microservice".
The example in this section currently uses "micro-service". To align with standard spelling conventions and the static analysis hint, consider changing it to "microservice".-"An application can be a micro-service, IoT (Internet of things) device (for example, a sensor), mainframe process, and more. +"An application can be a microservice, IoT (Internet of things) device (for example, a sensor), mainframe process, and more.🧰 Tools
🪛 LanguageTool
[misspelling] ~12-~12: This word is normally spelled as one.
Context: ...s an example: "An application can be a micro-service, IoT (Internet of things) device (for e...(EN_COMPOUNDS_MICRO_SERVICE)
37-37: Consistency: Update "Asyncapi's" to "AsyncAPI's".
For consistency with the document title and standard usage, change "Asyncapi's" to "AsyncAPI's".-Asyncapi's content and documentation follows American English spelling standards. Here are some preferred spelling of certain words: +AsyncAPI's content and documentation follows American English spelling standards. Here are some preferred spelling of certain words:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/styleguide/grammar.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/styleguide/grammar.md
[misspelling] ~12-~12: This word is normally spelled as one.
Context: ...s an example: "An application can be a micro-service, IoT (Internet of things) device (for e...
(EN_COMPOUNDS_MICRO_SERVICE)
[uncategorized] ~40-~40: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...
(EN_WORD_COHERENCY)
🪛 markdownlint-cli2 (0.17.2)
docs/styleguide/grammar.md
17-17: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
55-55: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
59-59: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
60-60: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
docs/styleguide/grammar.md
Outdated
| - Spelled-out acronyms unless they are proper nouns (API, HTTP, URL) | ||
| - Articles (a, an, the) | ||
| - Conjunctions (and, but, or, nor, for, so, yet) unless they are part of a title or heading ("Parameters in channel address")## Spelling | ||
| AsyncAPI's content and documentation follows American English spelling standards. Here are some preferred spelling of certain words: |
There was a problem hiding this comment.
I wouldn't assume we use American English. Personally, I use British English for all my docs because that's the English language I know. Rather, remove this sentence or reconstruct it @CBID2 to be inclusive for all
Co-authored-by: V Thulisile Sibanda <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
docs/styleguide/grammar.md (3)
7-15: Refine phrasing and remove leading space in the Abbreviations section
- Line 9: The wording "After that, use the abbreviation and acronym for them" is awkward. Consider simplifying to something like:
"Then use the acronym going forward."
- Line 14: Remove the leading space before "By using acronyms …".
44-44: Fix heading indentation for the Spelling section
Remove the extra space so the heading marker starts at column 0:- ## Spelling + ## Spelling🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
44-44: Headings must start at the beginning of the line
null(MD023, heading-start-left)
45-50: Reconsider specifying "American English" exclusively
To be inclusive of all contributors, you might use a more general term like "English" or simply reference style guides without tying to a particular variant.🧰 Tools
🪛 LanguageTool
[uncategorized] ~48-~48: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...(EN_WORD_COHERENCY)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/styleguide/grammar.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/styleguide/grammar.md
[uncategorized] ~48-~48: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...
(EN_WORD_COHERENCY)
🪛 markdownlint-cli2 (0.17.2)
docs/styleguide/grammar.md
44-44: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
🔇 Additional comments (5)
docs/styleguide/grammar.md (5)
1-5: Frontmatter formatting is correct
The YAML frontmatter is well‑formed with---delimiters, metadata fields, and a blank line following the closing---.
16-23: Active Voice examples look good
The DO and DON’T examples clearly contrast active vs. passive constructions and require no changes.
25-43: Capitalization rules are clear and consistent
List items and sub‑list indentations follow Markdown conventions and the guidance is easy to follow.
51-56: Verb Tense examples are effective
The DO (present) vs. DON’T (past) sentences accurately demonstrate the desired tense usage.
64-68: Additional Resources section is well‑structured
External links are correctly formatted and point to the intended style guides.
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/styleguide/grammar.md (1)
59-63: 🛠️ Refactor suggestionUpdate the “DON’T” example to remove personal pronouns
The current DON’T still uses “you,” which conflicts with the guideline to illustrate impersonal tone.Apply this diff:
- ❌ **DON'T:** "You should add parameters to the `channel.address` by placing a parameter between curly braces like {braces}. After that, you need to use `channel.parameters` to define your parameters. Finally, you should leverage `components.parameters` to enable reusable parameters' definitions across multiple channels." + ❌ **DON'T:** "Parameters can be added to the `channel.address` by placing them between curly braces (e.g., `{braces}`). Subsequently, `channel.parameters` defines parameters, and `components.parameters` enables reusable definitions across multiple channels."
🧹 Nitpick comments (2)
docs/styleguide/grammar.md (2)
16-24: Tighten up leading whitespace in Active Voice section
Remove the extra space before the paragraph and ensure consistent left alignment for headings and text.Apply this diff:
- When writing documentation and other forms of content for AsyncAPI, use active voice whenever possible. Here's an example: +When writing documentation and other forms of content for AsyncAPI, use active voice whenever possible. Here's an example:
64-68: Fix indentation in Additional Resources paragraph
Remove the extra leading spaces to align the paragraph with the section heading.Apply this diff:
- If you're looking for more information on grammar and style, consider checking out the following guides: +If you're looking for more information on grammar and style, consider checking out the following guides:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/styleguide/grammar.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/styleguide/grammar.md
[uncategorized] ~48-~48: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...
(EN_WORD_COHERENCY)
🪛 markdownlint-cli2 (0.17.2)
docs/styleguide/grammar.md
44-44: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
🔇 Additional comments (3)
docs/styleguide/grammar.md (3)
1-5: Front Matter Check: Approve YAML configuration
The YAML front matter is well‑formed with cleartitle,description, andweightfields enclosed by---.
25-43: Capitalization section looks solid
The rules and examples for capitalization are clear and align with standard title‑case conventions.
51-56: Verb Tense section is well‑written
The guidance and examples for present‑tense usage are clear and on‑point.
docs/styleguide/grammar.md
Outdated
| When using abbreviations and acronyms, write the full word with the acronym or abbreviation in parenthesis. After that, use the abbreviation and acronym for them. Here's an example: | ||
|
|
||
| > An application can be a microservice, IoT (Internet of things) device (for example, a sensor), mainframe process, and more. | ||
| > That aspect is particularly beneficial in setups like IoT, where topics are often assigned per device or device segment. | ||
|
|
||
| By using acronyms and abbreviations effectively, users would easily understand the context and meaning of the abbreviation or acronym and how it relates to the tutorial or guide. |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Refine the abbreviations section for clarity and correctness
- Change “parenthesis” to “parentheses.”
- Rework phrasing to follow the common pattern: full term followed by acronym in parentheses, then use the acronym thereafter.
- Capitalize “Internet of Things” in the spelled‑out version of IoT.
Apply this diff:
- When using abbreviations and acronyms, write the full word with the acronym or abbreviation in parenthesis. After that, use the abbreviation and acronym for them. Here's an example:
+ When using abbreviations and acronyms, write the full term followed by the acronym in parentheses. After that, use the acronym for subsequent references. Here's an example:
- > An application can be a microservice, IoT (Internet of things) device (for example, a sensor), mainframe process, and more.
+ > An application can be a microservice, IoT (Internet of Things) device (for example, a sensor), mainframe process, and more.
- By using acronyms and abbreviations effectively, users would easily understand the context and meaning of the abbreviation or acronym and how it relates to the tutorial or guide.
+ By using acronyms and abbreviations effectively, users can easily understand their context and meaning within the tutorial or guide.📝 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.
| When using abbreviations and acronyms, write the full word with the acronym or abbreviation in parenthesis. After that, use the abbreviation and acronym for them. Here's an example: | |
| > An application can be a microservice, IoT (Internet of things) device (for example, a sensor), mainframe process, and more. | |
| > That aspect is particularly beneficial in setups like IoT, where topics are often assigned per device or device segment. | |
| By using acronyms and abbreviations effectively, users would easily understand the context and meaning of the abbreviation or acronym and how it relates to the tutorial or guide. | |
| When using abbreviations and acronyms, write the full term followed by the acronym in parentheses. After that, use the acronym for subsequent references. Here's an example: | |
| > An application can be a microservice, IoT (Internet of Things) device (for example, a sensor), mainframe process, and more. | |
| > That aspect is particularly beneficial in setups like IoT, where topics are often assigned per device or device segment. | |
| By using acronyms and abbreviations effectively, users can easily understand their context and meaning within the tutorial or guide. |
There was a problem hiding this comment.
@CBID2 this is a valid review
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!
docs/styleguide/grammar.md
Outdated
| ## Spelling | ||
| Here are some preferred spellings of certain words: | ||
| - Use "color" instead of "colour" | ||
| - Use "center" instead of "centre". | ||
| - Use "organization" instead of "organisation". | ||
| - Use "program" instead of "programme" | ||
|
|
There was a problem hiding this comment.
Fix heading indentation and unify bullet punctuation
- Remove the leading space before the “## Spelling” heading (MD023).
- Standardize bullet punctuation: either drop trailing periods on all items or add them consistently.
Apply this diff:
- ## Spelling
+## Spelling
- - Use "center" instead of "centre".
+ - Use "center" instead of "centre"
- - Use "organization" instead of "organisation".
+ - Use "organization" instead of "organisation"
- - Use "program" instead of "programme"
+ - Use "program" instead of "programme"📝 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.
| ## Spelling | |
| Here are some preferred spellings of certain words: | |
| - Use "color" instead of "colour" | |
| - Use "center" instead of "centre". | |
| - Use "organization" instead of "organisation". | |
| - Use "program" instead of "programme" | |
| ## Spelling | |
| Here are some preferred spellings of certain words: | |
| - Use "color" instead of "colour" | |
| - Use "center" instead of "centre" | |
| - Use "organization" instead of "organisation" | |
| - Use "program" instead of "programme" |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~48-~48: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...ntre". - Use "organization" instead of "organisation". - Use "program" instead of "programm...
(EN_WORD_COHERENCY)
🪛 markdownlint-cli2 (0.17.2)
44-44: Headings must start at the beginning of the line
null
(MD023, heading-start-left)
There was a problem hiding this comment.
@thulieblack Thanks for confirming! I'll implement the suggested changes to fix the heading indentation and standardize the bullet point punctuation by removing the trailing periods. This will ensure consistent formatting throughout the grammar style guide.
There was a problem hiding this comment.
Hey @thulieblack I made this and the other coderabbitai comment that you mentioned.
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!
|
@TRohit20 final review |
|
@CBID2 check some of the nitpicks and suggestion on code rabbit, I'll come do the last review |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/styleguide/grammar.md (2)
14-14: Remove unnecessary leading spaces for consistent Markdown formatting.Several paragraphs and examples are indented by one or more spaces, which can lead to inconsistent rendering and markdownlint warnings. Please outdent these lines so content aligns uniformly:
- By using acronyms and abbreviations effectively, users can easily understand their context and meaning within the tutorial or guide. +By using acronyms and abbreviations effectively, users can easily understand their context and meaning within the tutorial or guide. - When writing documentation and other forms of content for AsyncAPI, use active voice whenever possible. Here's an example: +When writing documentation and other forms of content for AsyncAPI, use active voice whenever possible. Here's an example: - Use personal pronouns sparingly when writing tutorials and other forms of content for AsyncAPI to make them more human and approachable to users. Here's an example: +Use personal pronouns sparingly when writing tutorials and other forms of content for AsyncAPI to make them more human and approachable to users. Here's an example: - ✅ **DO:** "You can add parameters to the `channel.address` by adding a parameter between curly braces like {`braces`}. Next, use `channel.parameters` to define your parameters. Finally, leverage the `components.parameters` to enable reusable parameters' definitions across multiple channels." +✅ **DO:** "You can add parameters to the `channel.address` by adding a parameter between curly braces like {`braces`}. Next, use `channel.parameters` to define your parameters. Finally, leverage the `components.parameters` to enable reusable parameters' definitions across multiple channels." - If you're looking for more information on grammar and style, consider checking out the following guides: +If you're looking for more information on grammar and style, consider checking out the following guides:Also applies to: 18-18, 63-63, 65-65, 70-70
66-66: Clarify impersonal tone in the “DON’T” personal pronouns example.The current “DON’T” example still contains the pronoun “you,” which doesn’t clearly contrast with the guidance to limit personal pronouns. Consider replacing it with a truly impersonal construction. For example:
-❌ **DON'T:** "You should add parameters to the `channel.address` by placing a parameter between curly braces like {braces}. After that, you need to use `channel.parameters` to define your parameters. Finally, you should leverage `components.parameters` to enable reusable parameters' definitions across multiple channels." +❌ **DON'T:** "Parameters can be added to the `channel.address` by placing them between curly braces (e.g., `{braces}`). Subsequently, `channel.parameters` defines parameters, and `components.parameters` enables reusable definitions across channels."
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/styleguide/grammar.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/styleguide/grammar.md
[uncategorized] ~51-~51: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...entre" - Use "organization" instead of "organisation" - Use "program" instead of "programme"...
(EN_WORD_COHERENCY)
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/styleguide/grammar.md (1)
69-70:⚠️ Potential issueUpdate the DON'T example to remove personal pronouns.
The DON'T example in the Personal Pronouns section still uses "you," which contradicts the guideline. Replace it with an impersonal construction:- ❌ **DON'T:** "You should add parameters to the `channel.address` by placing a parameter between curly braces like {braces}. After that, you need to use `channel.parameters` to define your parameters. Finally, you should leverage `components.parameters` to enable reusable parameters' definitions across multiple channels." + ❌ **DON'T:** "Parameters can be added to the `channel.address` by placing them between curly braces (e.g., `{braces}`). Subsequently, `channel.parameters` define parameters, and `components.parameters` enable reusable definitions across channels."
🧹 Nitpick comments (2)
docs/styleguide/grammar.md (2)
14-15: Fix inconsistent indentation and list nesting.
Remove leading spaces before paragraphs and ensure nested list items are indented under their parent. For example:- By using acronyms and abbreviations effectively... +By using acronyms and abbreviations effectively... - When writing documentation... +When writing documentation... - - Conjunctions (and, but, or, nor, for, so, yet) unless… + - Conjunctions (and, but, or, nor, for, so, yet) unless… - Use personal pronouns sparingly... +Use personal pronouns sparingly... - If you're looking for more information... +If you're looking for more information...Also applies to: 18-18, 44-44, 65-65, 73-73
50-53: Ensure consistent bullet punctuation in the spelling list.
The Capitalization section ends list items with periods, but the Spelling list does not. To maintain consistency, either remove trailing periods everywhere or add them uniformly:- - Use "color" instead of "colour" + - Use "color" instead of "colour."🧰 Tools
🪛 LanguageTool
[uncategorized] ~52-~52: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...entre" - Use "organization" instead of "organisation" - Use "program" instead of "programme"...(EN_WORD_COHERENCY)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/styleguide/grammar.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/styleguide/grammar.md
[uncategorized] ~52-~52: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...entre" - Use "organization" instead of "organisation" - Use "program" instead of "programme"...
(EN_WORD_COHERENCY)
🔇 Additional comments (1)
docs/styleguide/grammar.md (1)
1-5: Excellent addition of a comprehensive grammar style guide.
This new documentation clearly covers all major grammar considerations for AsyncAPI content with well-structured examples and resources.
|
/rtm |
|
@CBID2, please open a follow-up PR, to update your doc as it is failing to build because of the curly braces write your curly brace examples like |
Hi @thulieblack! :) I made the PR. It's #1883 |
Description
This pull request adds a grammar style guide to ensure that the content written for AsyncAPI has consistently formatting. It focuses on and contains the following:
Related issue(s)
Closes #1691
Summary by CodeRabbit