AsyncAPI Initiative
2023 Google Season of Docs Case Study: AsyncAPI #961
Closed
quetzalliwrites
started this conversation in
Docs & Education
Replies: 5 comments
-
|
Congratulations for the year 2023! 🥳 |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
Amazing job! Congratulations! 👏👏👏 |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
Love it!!! |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
Great job y'all 👏 👏 👏 |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
That's an amazing insight @alequetzalli🔥 |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
✨ AsyncAPI Initiative: Bridge AsyncAPI Document Knowledge Gaps & Build Interactive Learning Paths
Organization or Project: AsyncAPI Initiative
Organization Description: AsyncAPI is currently on version 3.0.0 (pre-release); first released in 2016 as an Apache License 2.0 library under the Linux Foundation that seeks to improve the current state of Event-Driven Architectures (EDA).
Author: @alequetzalli
🤯 Problem Statement & Proposal Abstract
Our first identified challenge involved updating the documentation for the structure of an AsyncAPI document to align with the latest specification, version 3.0.0. This new version introduces numerous changes and features, necessitating a revision of the configuration guidelines for AsyncAPI documents. To facilitate easier implementation of Event-Driven Architectures (EDAs), our documentation needs to provide more comprehensive explanations of the different sections within an AsyncAPI document.
The second challenge we've addressed is the development of an introductory, interactive learning path for AsyncAPI, comprising five modules. Our new interactive educational resource will soon be available on our AsyncAPI Killercoda profile. To support this initiative, we've established a dedicated repository for interactive learning content at
https://github.com/asyncapi/learning-paths.Our new interactive learning path features a narrative where the AsyncAPI mascot Eve assists Chan in repairing his spaceship following an unexpected crash in Eve's backyard. Throughout this journey, various API concepts are elucidated using the engaging theme of fixing Chan's spaceship.
In "Module 1: Introduction to AsyncAPI," Chan's spaceship crash lands in Eve's backyard, serving as a backdrop to explore AsyncAPI, its usage, and real-world applications. The story progresses to "Module 2: Event-Driven Architectures," where Eve examines the spaceship's engine, introducing event-driven systems and their design using AsyncAPI, particularly for microservices. The "Module 3: AsyncAPI Specification" sees Eve helping Chan program his spaceship, delving into the AsyncAPI document structure, including its various components like info, channels, and schemas. The narrative continues with "Module 4: Creating and Validating AsyncAPI Code and Documents," where Chan returns to his planet to test communications with Eve, focusing on writing, validating, and hands-on exercises for AsyncAPI documents. The journey concludes with Module 5, a summary of the learning outcomes, a teaser about checking AsyncAPI tools, and a link back to the documentation.
note: 2023 AsyncAPI GSoD proposal
📝 Project Description
💡 Creating the proposal
The AsyncAPI 2023 Google Season of Docs (GSoD) proposal was originally proposed by @alequetzalli to the community in late 2022 via an open GitHub public discussion, 5 Proposed AsyncAPI Docs & Education Projects: 2023. Based on the community votes, the two projects that received the most votes were then proposed in AsyncAPI's 2023 Google Season of Docs application.
💸 Budget
AsyncAPI requested from Google a total US $10,300 budget for both proposed Docs projects. (i.e. $5,000 per project plus $300 for swag) We divided the grant funds equally amongst our 2023 GSoD interns and we'll be paying them once we receive the funds in December.
👩🏻💻 Participants
Of the 100+ candidates that applied, I (@alequetzalli) interviewed 30+. In the end, we hired 4 candidates to collaborate with us for GSoD this year: Mahfuza, Bhaswati, Rohit, and Hridyesh.
During the LIVE interviews, Alejandra divided the exercises into two parts: writing and editing. Candidates were given a document and asked to identify issues and potential solutions, then rewrite or edit the document as needed.
The following factors were considered when selecting candidates:
⌛ Timeline
Here is a short overview of our timeline:
first-time-ticketsto get each new TW contributor started.🙌🏽 Results
Here are the key achievements of AsyncAPI Docs for GSoD 2023:
request/replyfeature from version 3 has been comprehensively documented, enriching both our Concepts and Tutorials sections./AsyncAPI-documentsubdirectory within the Concepts area. That new section delves into the structure of an AsyncAPI document, with each component meticulously detailed on its own page.🔎 Analysis
What Went Well?
Despite being a few weeks behind in merging our 2023 GSoD pull requests (PRs), we're pleased with our significant achievements, especially in mentoring junior open-source software (OSS) technical writers. Our current delay mirrors last year's timeline, where we also experienced a slight lag in finalizing PRs but ultimately succeeded in fulfilling our project scope. We anticipate a similar outcome this year and look forward to applying our new insights to enhance our performance in the next year, pending our selection for 2024 GSoD.
We are also excited about the imminent integration of our new interactive learning path into the AsyncAPI Killercoda profile, marking it as our inaugural 100-level course. Incorporating a storyline and characters into our educational content represents a bold step in providing engaging and fun learning resources for our OSS community.
Challenges and Setbacks
We encountered a couple of challenges during the 2023 GSoD.
Firstly, among the four participants we hired, only three completed the program. Furthermore, not all participants consistently demonstrated dedication and commitment, leading to delays, especially in the latter part of the project. As such, we'll need a few additional weeks to merge the pending work.
Secondly, due to the impending release of spec version 3.0.0, our currently merged GSoD work is only accessible in the version 3 subdomain, visible at
https://v3.asyncapi.com/docs/. We opened a feature branch in our community for all updates related to version 3, which included documentation. Consequently, the GSoD merged work won't appear on our regular domain (asyncapi.com/docs) until the version 3 feature branch in our/websiterepository is merged into the main branch.Below are some of the GSoD documents merged into the aforementioned v3 subdomain:
Does AsyncAPI consider the project successful?
YES, absolutely! We're on the brink of merging the final PRs, and we've successfully integrated crucial documentation detailing the request/reply feature in version 3.0.0. It's gratifying to see new and relevant documentation in place, particularly as all our 2023 GSoD contributions align perfectly with the release of version 3.0.0. Additionally, it's particularly encouraging that one of our GSoD writers has shown interest in becoming a core documentation maintainer. Such achievements collectively signify multiple victories for the AsyncAPI Docs project!
❤️ Summary
In the future, if we participate in GSoD 2024, there are a few things we will do differently due to our learnings from 2023. In 2023 GSoD, we learned a valuable lesson: we were overstaffing our writing program in "Google Season of Docs." While we deeply value and focus on mentorship, a more balanced approach is needed. In 2024, we plan to adjust our hiring strategy. Instead of bringing on 3-4 writers per program, we'll aim to hire 1 or 2 writers. This shift will enhance our hiring budget, allowing us to recruit more skilled and dependable candidates. Targeting to hire fewer but more skilled writers also allows us to focus on providing higher-quality mentorship.
Lastly, I would love to give some parting advice for other projects trying to solve a similar problem with documentation: Don't be hesitant to hire juniors or minorities in tech who need mentoring. You will be surprised how quickly passion and a reliable work ethic supersede knowledge level.
👉🏽 Appendix
Beta Was this translation helpful? Give feedback.
All reactions