[ghost]

🦄 Hola

¡Hola, AsyncAPI community! 😄

For today's latest announcement around AsyncAPI Docs 📑, I wanted to share with all technical writers about our organization’s plan for participation in Google Season of Docs 2023 (GSoD). Any and all technical writers are welcome to come and interview with us for GSoD 2023 season, regardless of tech background or years of experience! At AsynAPI, we love mentoring folks who want to get involved in OSS, tech, and Docs. ❤️ If AsyncAPI is accepted into GSoD 2023, we will conduct interviews and review portfolios. Stay tuned!

As some may remember, last year, AsyncAPI participated successfully in GSoD 2022, and I wrote a case study summarizing the work involved and our results.

In anticipation of our application for this year, I have created a new AsyncAPI Slack channel named #temp-gsod-2023 that anyone can join! First, join our Slack workspace ☎️ and please respect our slack etiquette.🙂 Then join the #temp-gsod-2023 channel, our temporary channel, to coordinate GSoD 2023 setup. I'll publish regular updates on where we are in the application process, so stay tuned as the process continues. 🙂

Join the #temp-gsod-2023 slack channel for:

• Mentees identification
• Mentors identification
• Ideas identification
• Mentees, ideas, and mentors matching

Below is the project proposal we've submitted to GSoD 2023, and then we close with a reminder of how to get started as an AsyncAPI Docs contributor:

---

🙌🏾 Bridge AsyncAPI Document Knowledge Gaps & Build Interactive Learning Paths

❤️ About AsyncAPI

AsyncAPI (currently version 2.6.0, first released in 2016) is an Apache License 2.0 library under the Linux Foundation that seeks to improve the current state of Event-Driven Architectures (EDA). The AsyncAPI Initiative is a specification and growing set of open-source tools to help developers define asynchronous APIs and build and maintain EDAs. Developers familiar with OpenAPI (aka Swagger) for RESTful APIs will see strong similarities when using AsyncAPI. One common use case is generating documentation (HTML or Markdown) of an asynchronous API. The specification is both platform and language-agnostic. Current tooling includes support for common message brokers such as Apache Kafka and RabbitMQ and languages including Python, Java, and Nodejs. Our long-term goal is to make working with EDAs as easy as working with REST APIs. That goes from documentation to code generation, discovery to event management, and beyond. Our 150+ Open-Source (OSS) contributors are EDA enthusiasts from all around the world.

📑 About our Docs project

🔎 Our current Docs problems

First solution: cover AsyncAPI document sections in detail

First, the AsyncAPI documentation needs more in-depth explanations of the different sections of an AsyncAPI document to avoid difficulties in implementing EDAs.

Here are the individual sections of an AsyncAPI document we need to cover:

• AsyncAPI structure - Introduce all root elements, add short explanation of info, servers, channels, components, and their purpose.
• Adding variables to URL - Explain how to add variables to the server URL when parts of the URL may be different per runtime. Explain how these can be reused between two servers via components.serverVariables.
• Adding channel - Explain the purpose of channels, different names for it, and what users should put here. Add a simple channel there, and explain how it relates to the server. If you specify a channel and server, it is expected that a given channel is present on all servers. Explain that the 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, how many there can be, what kind of, and their purpose, and explain pub/sub.
• Securing operations - Explain that server security applies to all the operations in all channels. Still, if you have different security per operation, you can use the security prop at the operation level.
• Adding messages - Add a simple message as in previous examples, explain the most important parts, and explain there can be one or multiple (oneOf) under operation. Talk about contentType and add a note about defaultSchema. Also, show how to reuse components.
• Payload schema - More complex message example with payload added using JSON and Avro schemas, and explain how to specify them. Explain how to reuse schema from components.
• AsyncAPI reusable parts - Explain the $ref concept, introduce and explain that $ref can point to the same document, other documents in a local system, and external URLs.
• Reuse with traits - Explain how trait concepts work.
• Organizing document with tags - Explain different tags info in different parts of AsyncAPI and their purpose.
• Extending AsyncAPI specification - Explain what to do when the specification does not yet support something you need, some field is missing, and more.

Second solution: Interactive Learning Paths

Second, our only educational content is static AsyncAPI documentation; the community needs more engaging and interactive ways to learn AsyncAPI concepts and architecture. To make learning AsyncAPI more accessible and enjoyable, we propose creating interactive learning paths that incorporate best practices. Our solution is to create interactive learning paths with engaging videos, gamification elements, immersive storylines with eLearning characters, badges, quizzes, points systems, etc.

By integrating these elements, we aim to make the learning experience more enjoyable and rewarding for the entire community. We can have videos that showcase AsyncAPI in action and visual animations of AsyncAPI spec terms and architecture. We'd love to create a learning experience that is useful, fun, and interactive! The first learning paths would also be able to re-purpose content from the current AsyncAPI Docs content buckets of tutorials and concepts, which were created thanks to GSoD 2022.

In addition, we can create said interactive learning paths on the current Killercoda AsyncAPI profile ...

...or even host them with Linux Foundation interactive content.

🎯 Our Docs project’s scope

As a result, AsyncAPI is proposing two projects for the Google Season of Docs 2023:

1. Interactive Learning Paths: Our proposed solution aims to make learning AsyncAPI more enjoyable and accessible, reducing the learning curve and accelerating technology adoption by building interactive learning paths. By integrating best practices such as videos, gamification elements, immersive storylines, badges, quizzes, and a points systems in our learning paths, we can make the learning experience more rewarding and help OSS communities build better event-driven architectures with confidence.
2. Document the AsyncAPI document sections in detail: We will document the 12 sections of an AsyncAPI document, providing examples and use cases to help users understand how to code each section. By providing this information, we aim to improve the overall usability of the AsyncAPI document and make it easier for users to implement Event-Driven Architectures.

📏 Measuring our Docs project’s success

We will partially measure success in the Docs project by capturing specific feedback about these changes via our Docs feedback card, how many new OSS Docs contributors we gain from this effort, and by measuring engagement via our Docs analytics.

We will also track the number of views, likes, and shares of any new videos to measure user engagement. We'll even monitor user feedback to continue improving our videos further.

⌛ Timeline

The project will take approximately 4-6 months to complete, depending on the different levels of knowledge from diverse technical writers (TW) that might get involved. (At AsyncAPI, we want to work with any TW, regardless of their years of experience. We have a passion for mentorship, and we do not wish to have a bar that would prevent any TW from contributing to our OSS Initiative. We look forward to mentoring TW(s) who are completely new to tech and making them feel welcome!)

The timeline would look as follows:

• May: Orientation on how to contribute to AsyncAPI Initiative, organize Docs issues, and assign good first-time-tickets to get each new TW contributor started.
• June - August: Each TW goes through designated issues marked for first-time contributors and work set aside for GSoD 2023. Each TW starts creating documentation for the issues assigned/selected.
• September - October: We determine if we can complete both projects successfully and re-align priorities as needed.
• November- early December: Project completion and GSoD contributors receive some swag!

💸 Project budget

We'll set aside 2-3 mentors for our two proposed projects: documenting the AsyncAPI document sections in detail and creating educational videos. Should we be selected, AsyncAPI would like to request from Google a US $5000 budget for each project. For both projects, the request then totals a $10,000 budget. That said, we would also like to request an additional $350 dollars in our budget to provide cool swag for participants.

Budget item	Total Amount
Technical writer updates, reviews, edits AsyncAPI Interactive Learning Paths.	$5000
Technical writer updates, reviews, and edits AsyncAPI documentation section details.	$5000
Award swag to selected Technical Writers	$350
TOTAL	$10,350

---

👉🏽 Get started contributing to AsyncAPI Docs Today

Last but not least, don't forget that code isn't the only way to contribute to OSS; Dev Docs are a huge help that benefits the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️

To get started as a Docs contributor:

1. Familiarize yourself with our project's Contribution Guide and our Code of Conduct.
2. Head to our Docs GH Board here.
3. Pick an issue you would like to contribute and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. If there is no work done in that Docs issue yet and you've already received onboarding help, feel free to open a PR and get started!

🏷 Tag me in your AsyncAPI Doc PRs

Do you have a documentation contributor question, and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or GitHub Discussions via my GitHub handle, alequetzalli 🐙.

-A.Q. 👩🏻‍💻 and Canela 🐕‍🦺

Originally posted by @alequetzalli in https://github.com/asyncapi/community/discussions/601

[github-actions[bot]]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

looking at the title and that description is a copy of discussion I assume it was created by mistake. Closing