[📑 Docs]: Create docs for spec 3.0 release

[quetzalliwrites]

What Dev Docs changes are you proposing?

Per the scheduled release of spec 3.0 on June 2023, a major update to AsyncAPI docs is needed.

To this end, Jonas added a discussion point for Docs to upcoming Spec 3.0 community meetings. We'll use this time to help guide and support the community contributors who help us document these changes in docs in the weeks leading to the June release.

---

Overview of spec 3.0 release changes that require documentation:

• Request/reply feat: request/response support spec#847
• Operation/channel decoupling feat!: move operations to its own root object spec#806 + feat: add new channels object spec#827
• Operation action (pub/sub confusion) feat!: move operations to its own root object spec#806 + feat: add new channels object spec#827
• Unified referencing behavior (using $ref instead of string) feat: unify all referencing mechanisms spec#852
• Common metadata fields feat: add missed "metadata" fields in the Server/Channel/Operation Objects spec#796
• Moving root properties tags and externalDocs to info feat: move root tags and externalDocs to the info object spec#794
• Splitting out server URL into host and pathname feat: replace server url with server host and pathname spec#888
• More reusable objects in components feat: add more reusable objects to the components object spec#792

NEW docs tasks

To this end, we have created the following tasks in this Epic docs issue in an effort to outline each category the changes introduce:

• docs: request/reply #1434
• docs: operation/channel decoupling #1435
• docs: operation action (pub/sub confusion) #1436
• docs: unified referencing behavior (using $ref instead of string) #1437
• docs: common metadata fields #1438
• docs: moving root properties tags and externalDocs to info #1439
• docs: splitting out server URL into host and pathname #1440
• docs: more reusable objects in components #1441

---

⚠️ PLEASE NOTE:

• Each of these tasks converted to issues does not imply a single PR; the community should expect to review multiple PRs PER task issue because each spec change introduces updates across all Docs content buckets. (i.e., The request/reply change introduces a need to create a Concepts doc, document further in upcoming new Spec 3.0 docs, and implies huge changes to current tutorials.)
• I have NOT added the following points to these proposed tasks because @jonaslagoni specifically stated on March 15, 2023, spec 3.0 community meeting that those points are not yet confirmed for release:
  • Change how traits behave Application of message traits (intentionally) replacing existing attributes spec#505
  • Allow defining other schema formats in components

---

cc @GreenRover @fmvilas @jonaslagoni @AceTheCreator @thulieblack @derberg

Code of Conduct

• I agree to follow this project's Code of Conduct

[quetzalliwrites]

I will add descriptions to each task converted to issues later today... don't worry, i didn't forget to add that for us ✌️🙂

[jonaslagoni]

Added all the epics to the spec 3.0 todo list, just for me to track the overall progress, I will make sure to sync the progress from this issue once every few weeks 🙂

[akshatnema]

Hey @alequetzalli, I see that you intialised many issues for the new Doc tasks for the spec 3.0 release. Can you please specify docs: prefix to the issue titles so that it is easily recognisable as a Doc issue and do specify the description for required issues.

[quetzalliwrites]

Hey @alequetzalli, I see that you intialised many issues for the new Doc tasks for the spec 3.0 release. Can you please specify docs: prefix to the issue titles so that it is easily recognisable as a Doc issue and do specify the description for required issues.

@akshatnema You no help me? 🥹🥹🥹

🤣😜

[akshatnema]

@akshatnema You no help me? 🥹🥹🥹

I can only help you to add the prefix docs:. For description, you are best 😄 👍

[CatherineKiiru]

Hello @alequetzalli I would like to contribute to this project. I'd be happy to start on simple tasks that you don't mind outsourcing. Would that be possible?

[quetzalliwrites]

Hello @alequetzalli I would like to contribute to this project. I'd be happy to start on simple tasks that you don't mind outsourcing. Would that be possible?

@CatherineKiiru Yes, we hope to identify more doc contributors for Spec 3 updates! ✨ We'd love to have you work with us on some spec 3.0 docs tasks.

To get you started:

1. Please DM me in AsyncAPI Slack to give you the onboarding steps. (all new docs contributors get onboarding tasks before they're assigned their first task to help them be more successful)
2. We'll need more context from @jonaslagoni and diverse spec contributors to help you get started. (They are aware of this and have stated they will be available to do so soonish) For now, I think we will likely want to start by first assigning docs: request/reply #1434.

[CatherineKiiru]

Thank you! I'm sending a DM shortly

[smoya]

As far as I can see, the only feature that might require to be deep documented is the Request/Reply one. About the rest, it should be enough with the introduced Spec changes. However, we should review them again and improve the text to become more user friendly.

[quetzalliwrites]

@smoya Have you read the Concepts, Guides, and Tutorials? I would prefer you read them to make sure nothing else needs changes.

Also, if we only need to document request/reply, why did @jonaslagoni provide a more extensive list? Can you clarify why Jonas's original scope outlined in this issue is unnecessary?

[smoya]

@smoya Have you read the Concepts, Guides, and Tutorials? I would prefer you read them to make sure nothing else needs changes.

Also, if we only need to document request/reply, why did @jonaslagoni provide a more extensive list? Can you clarify why Jonas's original scope outlined in this issue is unnecessary?

As I mentioned in this Slack thread, im gonna work on that this week.

I will start working on this next week, identify all changes that should be done; changes, removals, and additions to the docs. And will keep you always posted then 🙌

[quetzalliwrites]

Ah ok, I didn't realize that Slack message implied you were going to read all the docs' content buckets. I wanted to make sure 😄✌🏽

Sounds great, thank you! I am already curious to see what you find and can't wait to start writing them with ya 💪🏿

[quetzalliwrites]

We'll use the info provided by Jonas in this PR for starting writing context: #660

[smoya]

For the record, I'm on parental leave for a month. Meaning I can help with that once I'm back (~19 June)

[quetzalliwrites]

We're not expecting anything from you @smoya! Take care of yourself and the family. ✌🏽

[quetzalliwrites]

done ✅