docs: tags in a AsyncAPI document

[TRohit20]

Description

As part of Google Season of Docs 2023 at AsyncAPI, we're going to write in-depth explanations of the different sections of an AsyncAPI document to avoid difficulties in implementing EDAs.

For this document issue, we'll be adding document about tags object in a AsyncAPI document and how it helps us organise the AsyncAPI document

Related issue
This task is part of the GSoD Docs EPIC: #1507.
Resolves #1518

[netlify]

✅ Deploy Preview for shimmering-choux-eb0798 ready!

Name	Link
🔨 Latest commit	8fa52d8
🔍 Latest deploy log	https://app.netlify.com/sites/shimmering-choux-eb0798/deploys/655680b088675d00086f06b6
😎 Deploy Preview	https://deploy-preview-1957--shimmering-choux-eb0798.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[AnimeshKumar923]

I've given some reviews from my side. Please take a look and provide your feedback @TRohit20

[derberg]

# yaml-language-server: $schema=https://raw.githubusercontent.com/asyncapi/spec-json-schemas/next-major-spec/schemas/3.0.0-without-%24id.json

asyncapi: 3.0.0

components:
  tags:
    speech:
      name: Speech
      description: All speech related topics.
    video:
      name: Video
      description: All video related topics.
      
info:
  title: AsyncAPI Documentation
  version: 1.0.0
  description: |
    This AsyncAPI document provides a overview
    of the event-driven system.
  tags:
    - $ref: '#/components/tags/speech'
    - $ref: '#/components/tags/audio'

servers:
  speech:
    host: localhost:5672
    description: RabbitMQ broker for sendind speech data.
    protocol: amqp
    tags:
      - $ref: '#/components/tags/speech'
  video:
    host: localhost:5673
    description: RabbitMQ broker for audio information.
    protocol: amqp
    tags:
       - $ref: '#/components/tags/video'

channels:
  getSpeech:
      address: 'application/speech/get'
      servers: 
        - $ref: '#/servers/speech'
      messages:
        voice:
          name: Voice
          summary: Add info about the voice stream data.
          tags:
            - $ref: '#/components/tags/speech'
  getVideo:
      address: 'application/video/get'
      servers: 
        - $ref: '#/servers/video'
      messages:
        voice:
          name: Video
          summary: Add info about the video data live bitrate and others.
          tags: 
            - $ref: '#/components/tags/video'

operations:
  onVoiceStreamed:
    title: Get speech data
    channel:
      $ref: '#/channels/getSpeech'
    action: receive
    tags:
      - $ref: '#/components/tags/speech'

  onVideoStreamed:
    title: Get video data
    channel:
      $ref: '#/channels/getVideo'
    action: receive
    tags:
      - $ref: '#/components/tags/video'

[derberg]

recording of feedback session about Tags between me and @TRohit20
https://fathom.video/share/A5nhygkH8Yva_EcHxGaNUHghnsWcA3RJ

[quetzalliwrites]

TW review done 😄✨✨

[derberg]

left some comments

my biggest doubts are with the visualizations, like there is too much content.

for example

there is a lot of additional information that do not bring value. And the biggest value we are missing from those is that they always explain tabs object but do not mention Reference Object

my suggestion:

• if, like in case of operation you want to show fields other than tags then my suggestion is to stick only to fields that are required. So for operation that would be only address and channel + you would add tag.
• if you want to keep visualization, you need to show $ref as alternative too, especially that they are really the core of new functionality and you anyway show them in the final example

[derberg]

I think you missed my comment about diagrams

also please check links - they will not work on website as you link to markdown files. Another request, always before you submit for review, check your document in the preview on the website, so you see how content is rendered and if links work (you have browser plugins for links validation)

hint - you folks in doc contributors group could come up with a cheat sheet for PR, like basic stuff to do before PR is ready for review (studio examples check, preview in website check for formatting, links validation). That would be super beneficial long term

[derberg]

did you see my comment -> #1957 (comment)

[quetzalliwrites]

/rtm