5 Proposed AsyncAPI Docs & Education Projects: 2023

[quetzalliwrites]

5 Proposed AsyncAPI Docs & Education Projects: 2023

Hello, lovely AsyncAPI Docs Community, 2022 GSoD interns, and beyond! We have many needs that need to be documented, but there are only so many OSS Docs contributors. ✌🏽😄

With this in mind, we have 4 amazing areas we can improve in, but we would like to hear from the community their vote on top 2 projects to select for 2023.

(Some of our 2022 GSoD Interns want to keep contributing, so they too want to better understand what are the proposed projects they may contribute to soon.)

Please leave a comment with your votes! 🗳

1) Barbaños Education Video Scripts

This past year Barbaño worked hard to produce many video scripts to create a 100 API and AscynAPI learning video series. You can see all here scripts and open PRs that still need community help here.

For this project, we need:

• more technical Spec contributors to help review her PRs and provide detailed feedback
• more OSS Docs contributors to help write and re-write scripts (GSoD folks... COUGH COUGH..HINT HINT 😂😂😂😂)
• record each of the videos and identify people who want to volunteer to be in these videos
• work with agency we've hired in past to create needed video animations to make videos top notch 😄

2) AsyncAPI Interactive Learning Content

Creating AsyncAPI Interactive Learning Content that incorporates some best practices, such as:

• Add engaging videos (Again, see Barbaño's Video Scripts work above)
• Gamify the training:
  • Integrate an immersive storyline and eLearning characters. (EX: Judy and Tom need to create an app with Kafka and AsyncAPI. Judy needs her app to be able to do yada yada...)
  • Badges
  • Quizzes
  • Points system
• Create Learning Paths on our Killercoda AsyncAPI profile. (This work has already begun during GSoD 2022 scope of work and will likely be partially done before 2023 is over.)

3) Add Protocol Specific Tutorial Docs

I know the community uses diff protocols, because everyone has diverse needs. Would the community say they need more tutorials with different protocol setups? IF so, which protocols do you need documented the most?

What do we think of this? (Ok to disagree if you have a better idea!)
EX: asyncapi.com/docs/tutorials/protocols

4) Document the AsyncAPI Document sections in detail: 12 NEW docs

Lukasz did the below amazing write up to help detail some items he knew were still missing in our Docs.

---

• AsyncAPI structure - intro to all root elements, short explanation of info, servers, channels, components and their purpose
• Adding variables to URL - explain how to add variables to server URL when there are parts of URL that maybe different per runtime. And explain how these can be reused between 2 servers using components.serverVariables
• Adding channel - explain purpose of channels, different names for it, what people should put here (some overlap with channel concept doc probably). Add simple channel there, and explain how it related to server, that if you specify a channel and server, it is expected that given channel is present on all servers, and explain that channel can also specify that it is present only on server A or server B
• Specifing dynamic parts of channel name - explain how to use and reuse parameters
• Adding operations - introduce operations, show many there can be, what kind of, their purpose, pub/sub explained
• Securing operations - explain that server security applies to all the operations to all channel, but if you have different security per operation then you can use security prop on operation level
• Adding messages - add simple message as in previous examples, explain most important parts, explain there can be one or multiple (oneOf) under operation. Talk about contentType and add note about defaultSchema. Also show how to reuse from components
• Payload schema - more complex message example with payload added using JSON Schema and also Avro schema, and explanation how to specify them. And schema reuse from components
• AsyncAPI reusable parts - talk about $ref concept, introduce and explain that $ref can point to the same document, other document in local system, and also external urls. What about password to external url? Say that for local references people should use components
• Reuse with traits - explain trait concept and how it works
• Organizing document with tags - explain different tags info in different parts of AsyncAPI, their purpose (in docs rendering for example)
• Extending AsyncAPI specification - explain what to do when something you need is not yet supported by the specification, some field is missing or stuff like that. Explain that one way is to contribute (link) another to use -x <- and this is the core of this document, show extensions in action

---

5) Create AsyncAPI Style Guide

⚠️ Folks already asked if this could be proposed as a 2023 GSoD project, so adding this for us to vote on until Feb 15 when applications open. ⚠️

➡️ AsyncAPI Style Guide Docs issue: asyncapi/website#1240

In tech jobs, we often focus on our technology's technical aspects, such as functionality and performance. However, the documentation for our technology is equally important to the code itself. A style guide ensures consistency and clarity, establishes a consistent voice and tone in your documentation, makes it easier for multiple writers to work together on a single doc, and helps ensure documentation is accurate and up-to-date. When all of your technical writers follow the same guidelines, it's easier for readers to find the information they need and understand how to use your product or OSS technology.

[thulieblack]

I think we should go with 1, 2, and 4. I'm particularly interested in working on 1 & 2 starting in Jan if @Barbanio doesn't mind tutoring me😅😅

[Barbanio]

@thulieblack, how great to work together! We will learn from each other 🙂

[quetzalliwrites]

Thank you for the vote @thulieblack!

And you will LOVE working with @Barbanio, she's the sun 🌞 ! 😄

[Annysah]

I vote for 2, 3 and 4 🥳 🚀

[nelsonmic]

I vote 1,3 and 4

[Amishakumari544]

@alequetzalli I also want to be the part of next gsod 2023 and voting for 2,3,4 😄

[soma2000-lang]

Hello @alequetzalli I vote for 2 ,3,4

[Florence-Njeri]

Hi @alequetzalli, I vote for 1,3, and 4. I'd love to contribute to 1 and 4

[Souvikns]

I vote for 1,2 and 3

[derberg]

I vote 1, 3 and 4 ❤️

[Barbanio]

I vote for 1 🙃, 2, and 4.

[octonawish-akcodes]

I want to take part and contribute to the community too as I am new to the community so I will vote for 1, 2, and 4 :)

[quetzalliwrites]

📢 Some of you may notice we have updated the requirements to select a maximum of 2 projects; this is because after giving it much thought, I have decided these projects require much time and so I do not believe we will have time for 3 GSoD projects.
I already ran this program last year and I have a good idea of how much time/etc our contributors have, so I want us to keep our 2023 GSoD application realistic so that we set ourselves up for success.

[quetzalliwrites]

⚠️ VOTE 2 top projects to submit in 2023 GSoD ⚠️
I have added the AsyncAPI Style Guide docs issue asyncapi/website#1240 to the proposed projects set up for a vote for our application to 2023 GSoD. (i.e., the whole community needs to vote again to help decide what projects we will submit for 2023 GSoD)

[starlightknown]

I vote for 1,2 and I would love to volunteer for 1 if possible. These are great for projects but I feel style guide is necessary too and if not in GSoD we can plan on making it a General issue maybe and contribute?

[BhaswatiRoy]

2 & 3

[Florence-Njeri]

I vote for 3 & 4.

[thulieblack]

1 and 4

[Annysah]

I vote for 2 & 4

[octonawish-akcodes]

I vote for 2 & 4

[akshatnema]

I vote for 2 & 4.

[pratik9315]

I vote for 2 & 4

[peter-rr]

1 & 4 ❤️

[janvi01]

I vote for 1 & 4

[anmode]

I vote for 1 & 5. I am really interested to work on Create AsyncAPI Style Guide. I hope I get a chance to work on this!

[thulieblack]

Hey everyone. Due to the level of technicality required for video scripts, I suggest that it shouldn't be added as part of the GSoD project proposal. Currently, we have two projects to consider as a replacement one being the AsyncAPI Interactive Learning Content and the other being the Protocol-Specific Tutorial Docs

My Proposal

1. Choose the second most-voted project (which is Interactive Learning Content) from the list.
2. Revote between the two suggested projects.

With that in mind, I would love to hear your suggestions and votes as we have until March 23rd to make the necessary changes to our proposal.
cc @alequetzalli @derberg

[thulieblack]

I think there's a misunderstanding, we have finalized the GSoD project proposal.

Except, I'm suggesting we replace the Educational Videos project listed on our proposal due to the level of technicality. Hence I proposed to either:

1. Choose the second most-voted project (which is Interactive Learning Content) from the list.

Or

2. Revote between Protocol-Specific Tutorial Docs vs AsyncAPI Interactive Learning Content

Hey everyone. Due to the level of technicality required for video scripts, I suggest that it shouldn't be added as part of the GSoD project proposal. Currently, we have two projects to consider as a replacement one being the AsyncAPI Interactive Learning Content and the other being the Protocol-Specific Tutorial Docs

My Proposal

1. Choose the second most-voted project (which is Interactive Learning Content) from the list.
2. Revote between the two suggested projects.

With that in mind, I would love to hear your suggestions and votes as we have until March 23rd to make the necessary changes to our proposal. cc @alequetzalli @derberg

[quetzalliwrites]

Yes, and indeed, this is what we've all been discussing more or less offline ...turns out, it makes more sense to replace that project in GSoD for another one that got most votes too.

[quetzalliwrites]

All, keep in mind that we may possibly add interactive learning content in the Linux Foundation education platform. It is currently in discussions and I have no doubt we're going to vote as a community on this too. (or who knows, they may have already voted and I missed that public discussion 😂 😅 )

[quetzalliwrites]

Yes all, vote for 1 project, not 2. (we're voting to swap ONE project out, not two)

[Preshh0]

I think there's a misunderstanding, we have finalized the GSoD project proposal.

Except, I'm suggesting we replace the Educational Videos project listed on our proposal due to the level of technicality. Hence I proposed to either:

1. Choose the second most-voted project (which is Interactive Learning Content) from the list.

Or

2. Revote between Protocol-Specific Tutorial Docs vs AsyncAPI Interactive Learning Content

Hey everyone. Due to the level of technicality required for video scripts, I suggest that it shouldn't be added as part of the GSoD project proposal. Currently, we have two projects to consider as a replacement one being the AsyncAPI Interactive Learning Content and the other being the Protocol-Specific Tutorial Docs

My Proposal

1. Choose the second most-voted project (which is Interactive Learning Content) from the list.
2. Revote between the two suggested projects.

With that in mind, I would love to hear your suggestions and votes as we have until March 23rd to make the necessary changes to our proposal. cc @alequetzalli @derberg

@thulieblack, number 2's statement about revoting, is that AsyncAPI Interactive Learning Content or AsyncAPI Style Guide?

[Queen-codes]

I'm voting 2 and 5

[ro4i7]

I vote for 3,4 & 5

[quetzalliwrites]

Hey all, only vote for 1 project :)

we are only replacing 1 project, not BOTH in the proposal.

[Preshh0]

I vote number 2 then; the Interactive Learning Content. @alequetzalli @thulieblack

[thulieblack]

@alequetzalli seems like Interactive Learning is the way to go

[DhanyaHegde01]

I vote for 2, @alequetzalli

[king-Alex-d-great]

I hope I'm not too late for the party! 😀 I am voting for project 2 because I like the keywords 'engaging' and 'gamify'.

[rukundob451]

@alequetzalli, kindly wanted to inquire which project is available for mentorship for the 3rd phase?