docs: improve writing style for tags #3411
Conversation
bandantonio
requested review from
asyncapi-bot-eve and
quetzalliwrites
as code owners
WalkthroughThe pull request revises the AsyncAPI "Tags" documentation by simplifying definitions, restructuring explanations of the Changes
Assessment against linked issues
Assessment against linked issues: Out-of-scope changesNo out-of-scope changes identified. Suggested labels
Suggested reviewers
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3411 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 22 22
Lines 778 778
Branches 144 144
=========================================
Hits 778 778 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-3411--asyncapi-website.netlify.app/ |
![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
🧹 Outside diff range and nitpick comments (4)
markdown/docs/concepts/asyncapi-document/tags.md (4)
14-14: Consider using "brief" instead of "short".To strengthen the writing style, consider replacing "short" with "brief" in the description property definition.
-- `description`: A short description explaining the tag's purpose or usage. ++ `description`: A brief description explaining the tag's purpose or usage.🧰 Tools
🪛 LanguageTool
[uncategorized] ~14-~14: Loose punctuation mark.
Context: ...e: The name of the tag. -description`: A short description explaining the tag'...(UNLIKELY_OPENING_PUNCTUATION)
[style] ~14-~14: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...The name of the tag. -description: A short description explaining the tag's purpos...(QUICK_BRIEF)
66-67: Improve bullet point consistency.The bullet points have inconsistent formatting. Consider making them parallel in structure.
-- criteria like location, environment type (like production or development), and unique server features. -- specific tags or labels. ++ Location, environment type (production/development), and unique server features ++ Specific tags and labels for server identification
Line range hint
239-254: Fix YAML indentation.The YAML example needs consistent indentation for better readability.
-name: SimpleSignup -summary: A simple UserSignup example message -tags: - - name: userSignUp - description: some message related to user signup -headers: - correlationId: my-correlation-id - applicationInstanceId: myInstanceId -payload: - user: - someUserKey: someUserValue - signup: - someSignupKey: someSignupValue +name: SimpleSignup +summary: A simple UserSignup example message +tags: + - name: userSignUp + description: some message related to user signup +headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId +payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue
338-338: Remove unused link reference.The link reference
[components-field]is not used in the document.-[components-field]: /docs/concepts/asyncapi-document/structure#components-field🧰 Tools
🪛 Markdownlint
338-338: Unused link or image reference definition: "components-field"
Link and image reference definitions should be needed(MD053, link-image-reference-definitions)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
markdown/docs/concepts/asyncapi-document/tags.md(14 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/concepts/asyncapi-document/tags.md
[uncategorized] ~13-~13: Loose punctuation mark.
Context: ...ains the following properties: - name: The name of the tag. - description: A...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~14-~14: Loose punctuation mark.
Context: ...e: The name of the tag. - description`: A short description explaining the tag'...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~14-~14: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...The name of the tag. - description: A short description explaining the tag's purpos...
(QUICK_BRIEF)
[uncategorized] ~15-~15: Loose punctuation mark.
Context: ...tag's purpose or usage. - externalDocs: Additional external documentation for t...
(UNLIKELY_OPENING_PUNCTUATION)
🪛 Markdownlint
markdown/docs/concepts/asyncapi-document/tags.md
338-338: Unused link or image reference definition: "components-field"
Link and image reference definitions should be needed
(MD053, link-image-reference-definitions)
🔇 Additional comments (3)
markdown/docs/concepts/asyncapi-document/tags.md (3)
Line range hint 22-60: LGTM! Clear explanation with consistent styling.
The section effectively explains tags in the info object context, with well-structured visual representation and practical examples.
Line range hint 116-164: LGTM! Well-structured explanation with clear examples.
The section effectively explains channel tags with appropriate visual aids and examples.
Line range hint 165-216: LGTM! Comprehensive coverage of operations tags.
The section provides a thorough explanation with well-structured examples and diagrams.
|
/update |
sambhavgupta0705
added
📑 docs
area/docs
|
This pull request has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this pull request, add a comment with detailed explanation. There can be many reasons why some specific pull request has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this pull request forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
|
Not stale, still waiting for review. |
- Made doc sections more consistent - Replace duplicated styling in mermaid diagram with classes - Update yaml examples to use consistent formatting and descriptions
bandantonio
force-pushed
the
docs/tags-doc-improve-writing-style
branch
from
aac3385 to
9e2919b
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (11)
markdown/docs/concepts/asyncapi-document/tags.md (11)
7-11: Unify introductory definitions for clarity
The opening sentences on lines 7, 9, and 11 repeat similar context. Consider consolidating into a single, concise introduction, for example:
“Thetagsfield is an array of [tag objects][tag-object] defined under theinfoobject. Each tag has these properties:”
This avoids redundancy and makes the doc even more direct.
14-14: Prefer “brief” over “short” for conciseness
To strengthen the wording, replace “A short description explaining…” with “A brief description explaining…”.🧰 Tools
🪛 LanguageTool
[uncategorized] ~14-~14: Loose punctuation mark.
Context: ...e: The name of the tag. -description`: A short description explaining the tag'...(UNLIKELY_OPENING_PUNCTUATION)
[style] ~14-~14: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...The name of the tag. -description: A short description explaining the tag's purpos...(QUICK_BRIEF)
17-19: Split into two sentences and use active voice
Line 17–19 is a long compound sentence. For readability, break it up and use active constructions, e.g.:
“Tags serve two main purposes. You can define global tags underinfofor document-wide grouping, or apply tags directly to components (servers, channels, operations) for more targeted categorization.”
22-22: Shorten phrasing to improve flow
On line 22, consider trimming “specified in thetagsproperty of theinfoobject categorize the entire AsyncAPI document” to
“Tags underinfocategorize the document by functional area.”
49-49: Consolidate multi-line description into one sentence
The YAML example’s description block is split over two lines without final punctuation. Consider combining into a single sentence with a period:description: "This AsyncAPI document provides an overview of the event-driven system."This ensures grammatical completeness.
Also applies to: 275-275
52-52: Enforce hyphenation for compound modifiers
In example descriptions, use hyphens consistently:
application-related topicstime-related topicsspeech-related topicsvideo-related topics
This prevents ambiguity in compound adjectives.Also applies to: 57-57, 265-265, 268-268
64-67: Consistent bullet list punctuation
Under “tags in servers,” bullets 66 and 67 end with periods, but some lists elsewhere don’t. Either add periods to all or remove them for consistency.
69-69: Unify “optional” phrasing across sections
Each component section notes optional usage differently. Recommend a single pattern, e.g.:
“Applying tags at the<component>level is optional.”
This consistent phrasing improves scan-ability.Also applies to: 118-118, 167-167, 219-219
99-99: Refine example descriptions for clarity
Standardize the environment descriptions in servers:
- “development AMQP broker” → “AMQP broker for development”
- “This environment is meant for developers to run their tests” → “AMQP broker used for development testing”
- “RabbitMQ broker for the production environment” → “AMQP broker for production”
- “live environment available for final users” → “production broker available to end users”
- “RabbitMQ broker for sending speech data” → “AMQP broker for speech data”
- “RabbitMQ broker for video information” → “AMQP broker for video data”
This tightens wording and aligns style.Also applies to: 103-104, 107-107, 111-112, 283-283, 289-289
198-198: Use imperative present tense in summaries
On line 198, changesummary: Action to sign a user upto
summary: Sign up a userThis matches conventional summary style in AsyncAPI examples.
256-256: Break long sentences for readability
Line 256 is a lengthy lead-in. Consider splitting:
“Below is an example of tags defined undercomponents. The tags are then referenced in servers and channels.”
This makes it easier to digest.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
markdown/docs/concepts/asyncapi-document/tags.md(14 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/concepts/asyncapi-document/tags.md
[uncategorized] ~13-~13: Loose punctuation mark.
Context: ...ains the following properties: - name: The name of the tag. - description: A...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~14-~14: Loose punctuation mark.
Context: ...e: The name of the tag. - description`: A short description explaining the tag'...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~14-~14: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...The name of the tag. - description: A short description explaining the tag's purpos...
(QUICK_BRIEF)
[uncategorized] ~15-~15: Loose punctuation mark.
Context: ...tag's purpose or usage. - externalDocs: Additional external documentation for t...
(UNLIKELY_OPENING_PUNCTUATION)
🪛 markdownlint-cli2 (0.17.2)
markdown/docs/concepts/asyncapi-document/tags.md
338-338: Link and image reference definitions should be needed
Unused link or image reference definition: "components-field"
(MD053, link-image-reference-definitions)
⏰ Context from checks skipped due to timeout of 180000ms (1)
- GitHub Check: Test NodeJS PR - macos-13
| class B,F,I,K,G cyanColor; | ||
| classDef cyanColor fill:#47BCEE,stroke:#000; |
There was a problem hiding this comment.
🛠️ Refactor suggestion
DRY up repeated Mermaid styling
Each diagram repeats the same classDef blocks. Extract the shared class definitions into a single include or partial (e.g., _includes/mermaid‐styles.md) and reference it in each block to avoid duplication.
Also applies to: 83-84, 139-140, 188-189, 234-235
thulieblack
changed the title
thulieblack
changed the title
| tags: | ||
| - $ref: '#/components/tags/video' | ||
| ``` | ||
|
|
There was a problem hiding this comment.
This whole section is not rendering correctly on the website.
|
@bandantonio any update? |
|
@sambhavgupta0705 will update the PR today, didn't spot the issue immediately |
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
markdown/docs/concepts/asyncapi-document/tags.md (1)
240-254: YAML snippet is invalid due to leading spaces and inconsistent indentationExtra leading spaces on lines 241–243 shift the root level and break parsing. Suggested fix:
- name: SimpleSignup -summary: A simple UserSignup example message -tags: - - name: userSignUp - description: some message related to user signup +name: SimpleSignup +summary: A simple UserSignup example message +tags: + - name: userSignUp + description: Some message related to user signupWithout correct indentation, readers cannot copy-paste and validate the example.
♻️ Duplicate comments (1)
markdown/docs/concepts/asyncapi-document/tags.md (1)
36-38: Mermaid styling duplication still presentThe identical
classDef cyanColorand repeatedclass … cyanColor;blocks re-appear in every diagram. Please extract the style into a shared include to keep the markdown DRY (see earlier comment).Also applies to: 83-85, 139-141, 188-190, 234-236
🧹 Nitpick comments (3)
markdown/docs/concepts/asyncapi-document/tags.md (3)
11-16: Clarify that the listed properties belong to each tag object, not thetagsfield itselfThe current wording (“The individual
tagsfield contains the following properties”) might mislead readers into thinking thetagsarray itself holds these keys. In reality, each tag object inside that array carries them.-The individual `tags` field contains the following properties: +Each tag object in the `tags` array can contain the following properties:
17-20: Tighten the “either … or” sentence to remove the extra andThe conjunction sequence breaks the either/or construction and reads awkwardly.
-Tags have different purposes depending on the context. They can either be used for consistent tag usage across the AsyncAPI document and logical component grouping or be applied to individual components like ... +Tags serve two purposes: (1) consistent, document-wide grouping, or (2) targeted labelling of individual components such as ...
64-68: Bullet list mixes structure & example; split for clarityThe first bullet sets high-level criteria, the second repeats “specific tags or labels”, which is essentially the same idea. Consider merging or rewriting to avoid redundancy.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
markdown/docs/concepts/asyncapi-document/tags.md(13 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: asyncapi-bot
PR: asyncapi/website#0
File: :0-0
Timestamp: 2025-02-18T12:07:42.211Z
Learning: The following PR commands are supported in the asyncapi/website repository:
- `/please-take-a-look` or `/ptal`: Requests attention from reviewers who haven't reviewed the PR
- `/ready-to-merge` or `/rtm`: Triggers automerge when all conditions are met
- `/do-not-merge` or `/dnm`: Blocks automerge even if all conditions are met
- `/autoupdate` or `/au`: Adds autoupdate label to keep PR in sync with target branch
- `/update` or `/u`: One-time update of PR with latest changes from target branch
Learnt from: akshatnema
PR: asyncapi/website#3378
File: scripts/markdown/check-markdown.js:1-1
Timestamp: 2024-11-25T18:34:51.303Z
Learning: When reviewing `scripts/markdown/check-markdown.js`, optimizations should be addressed in separate issues and not included in the current pull request.
Learnt from: bandantonio
PR: asyncapi/website#4264
File: markdown/docs/tutorials/getting-started/coming-from-openapi.md:24-25
Timestamp: 2025-07-19T20:58:34.040Z
Learning: In the AsyncAPI website documentation, anchor references to specification sections can use camelCase format (e.g., #serverObject, #parameterObject, #messageObject) even if the actual HTML IDs on the spec page use hyphenated lowercase format. This is acceptable and should not be changed.
Learnt from: anshgoyalevil
PR: asyncapi/website#3557
File: tests/fixtures/markdown/check-edit-links-data.js:3-11
Timestamp: 2025-01-19T04:51:41.255Z
Learning: In the AsyncAPI website repository, the test data in `tests/fixtures/markdown/check-edit-links-data.js` intentionally includes inconsistent paths (with and without 'docs' prefix) to verify the script's ability to normalize and handle ambiguous path structures.
Learnt from: akshatnema
PR: asyncapi/website#3265
File: tests/fixtures/toolsObjectData.js:51-52
Timestamp: 2024-10-09T17:35:36.557Z
Learning: When reviewing code in the 'asyncapi/website' repository, akshatnema prefers that I do not provide committable code suggestions.
markdown/docs/concepts/asyncapi-document/tags.md (6)
Learnt from: bandantonio
PR: #4264
File: markdown/docs/tutorials/getting-started/coming-from-openapi.md:24-25
Timestamp: 2025-07-19T20:58:34.040Z
Learning: In the AsyncAPI website documentation, anchor references to specification sections can use camelCase format (e.g., #serverObject, #parameterObject, #messageObject) even if the actual HTML IDs on the spec page use hyphenated lowercase format. This is acceptable and should not be changed.
Learnt from: akshatnema
PR: #3262
File: components/navigation/BlogPostItem.tsx:80-87
Timestamp: 2024-10-11T11:17:32.246Z
Learning: In the BlogPostItem component, the parent Link wraps the entire content, so inner Link components around the title and excerpt are unnecessary.
Learnt from: akshatnema
PR: #3262
File: components/navigation/BlogPostItem.tsx:95-119
Timestamp: 2024-10-11T11:32:30.226Z
Learning: In the BlogPostItem component (components/navigation/BlogPostItem.tsx), nesting <a> tags inside the parent Link component leads to hydration issues; therefore, we should avoid nesting <a> tags inside Link components in this component.
Learnt from: akshatnema
PR: #3378
File: scripts/markdown/check-markdown.js:1-1
Timestamp: 2024-11-25T18:34:51.303Z
Learning: When reviewing scripts/markdown/check-markdown.js, optimizations should be addressed in separate issues and not included in the current pull request.
Learnt from: anshgoyalevil
PR: #3301
File: scripts/markdown/check-markdown.js:0-0
Timestamp: 2024-10-18T17:24:45.053Z
Learning: In scripts/markdown/check-markdown.js, the script is not run in an asynchronous environment, so refactoring it to use async/await is unnecessary.
Learnt from: TRohit20
PR: #4107
File: markdown/docs/tools/studio/architecture.md:23-23
Timestamp: 2025-05-09T17:35:57.171Z
Learning: In the AsyncAPI Studio architecture documentation, "Layer Breakdown" is intentionally structured as an H3 heading (subsection) because it provides additional detail about the layered architecture pattern introduced earlier, rather than being a standalone main section.
🪛 LanguageTool
markdown/docs/concepts/asyncapi-document/tags.md
[style] ~14-~14: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...The name of the tag. - description: A short description explaining the tag's purpos...
(QUICK_BRIEF)
⏰ Context from checks skipped due to timeout of 180000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Test NodeJS PR - windows-latest
|
@bandantonio any update |
|
@sambhavgupta0705 All done in 0230e9d |
|
/rtm |
4 participants
Description
Related issue(s)
Fixes #3410
See also #3375
Summary by CodeRabbit
tagsobject and its properties.tagsat theinfolevel to clarify their categorization role.