As an Open-Source (OSS) contributor, I volunteer to write periodic updates about the AsyncAPI Docs ecosystem.
I want to note that this is not an official AsyncAPI Initiative update, but a personal summary I'm volunteering to write up for the OSS community. The goal is to let you know what's going on in the Docs area and how the Docs area has been teaming with other areas within the AsyncAPI Initiative. 😀👍🏽
November brings the official close to 2022 GSoD! It also meant wrapping up our results, identifying left-over items to do, and writing the required Case Study for Google.
Please find below a copy of the public 2022 GSoD: AsynAPI Case Study submitted to Google. (All organization administrators must submit their case study and final project evaluation by November 30th.)
On December 14, 2022, Google will publish the 2022 Season of Docs case studies, aggregate project data, and announce who they considered to have finished successfully.
Organization or Project: AsyncAPI Initiative
Organization Description: AsyncAPI (currently version 2.3.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).
Author: @alequetzalli
Earlier this year, AsyncAPI Docs needed an Information Architecture (IA) makeover. Content buckets were poorly planned, with most onboarding content missing. There was a need for /Concepts docs that explain our spec terminology in more detail with engineering diagrams since people often learn visually. We also needed to add a new and broader /Tools content bucket for documenting the AsyncAPI tools ecosystem. We also wanted to expand our /Tutorials and start planning Troubleshooting Guides under a /Guides content bucket section.
The second problem we proposed as our second project was re-structuring and re-writing the Generator tool docs. (Because this is one of our main tools, it was big enough to qualify as its own independent project for GSoD 2022.)
note: 2022 AsyncAPI GSoD proposal
The AsyncAPI 2022 GSoD proposal was originally proposed by @alequetzalli to the community in late 2021. After several public community streams and a blog post proposal, the community got excited about giving our Docs and Educational content a major makeover. Since the excitement for the proposed Information Architecture changes was met with unanimous approval, it soon became clear that this project was the perfect idea to pitch for 2022 GSoD.
AsyncAPI requested from Google a total US $10,000 budget for both proposed Docs' projects. (i.e. $5,000 per project) We divided the grant funds equally amongst our 2022 GSoD interns and we'll be paying them once we receive the funds in December.
Looking back, we learned we should have also requested a small budget to account for the swag items we'll gift our GSoD participants.
| Budget item | Total Amount |
|---|---|
| Technical writer updates, reviews, edits, and publishing new documentation for the IA improvements. | $5000 |
| Technical writer updates, reviews, migration, and publishing improved Generator tool documentation. | $5000 |
| TOTAL | $10,000 |
Of the 200+ candidates that applied, I (@alequetzalli) interviewed 100+. I asked all candidates the same 3 questions: (1) In what areas of Technical Writing do you want to grow?; (2) How would you like to give back to the OSS community via your GSoD contributions if you're selected?; (3) Which project do you wish to join: Information Architecture makeover or Generator Tool docs? In the end, I selected 6 interns for GSoD 2022 at AsyncAPI.
- 🧕🏾 Anisat Akinbani (Nigeria 🇳🇬): Information Architecture, parent GSoD project.
- 💁🏾♀️ Florence Njeri (Kenya 🇰🇪): Generator Tool & Tools Docs, child GSoD project.
- 👩🏽💻 Karuna (India 🇮🇳): Information Architecture, parent GSoD project.
- 👨🏿💻 Nelson Michael (Nigeria 🇳🇬): Information Architecture, parent GSoD project.
- 💁🏾♂️ Pratik (India 🇮🇳): Generator Tool & Tools Docs, child GSoD project.
- 👩🏿💻 Thulie (Cape Town 🇿🇦): Information Architecture, parent GSoD project.
While no one dropped out, of the 6 participants, only 3-4 had the ability to be the most present and contribute consistently. We all learned as a group that project management requires honest communication from both ends to set realistic goals. We also learned that if time availability changes, communicating the life update immediately is part of being a professional. Lastly, all participants learned that Technical Writing requires a succinct approach, utmost attention to detail, and re-writing as many drafts as it takes to get the job done right.
Here is a short overview of our timeline; as you can see, the originally proposed timeline needed minor adjustments.
- May: Orientation on how to contribute to AsyncAPI Inititiave, how Docs issues are organized, detail how we're migrating Generator Tool Docs, and assigned good
first-time-ticketsto get each new TW contributor started. - June - August: Each TW went through designated issues marked for both first time contributors and work set aside for
GSoD 2022. Each TW starts creating documentation for their individual issues assigned/selected. - September - October: We re-aligned some priorities, because a couple of our participants had life and university events that slowed their contributions. We also incorporated a few new stretch goals, such as adding the Guides content bucket.
- November: Project is about 90% complete! We will soon be sending our GSoD contributors some swag and set up their payments in December!
- December: GSoD participants have offered to keep working on remaining open GSoD pull requests until all goals are met.
Let's outline the top 10 results that AsyncAPI Docs has to show for GSoD 2022.
AsyncAPI Docs now has a dedicated homepage with cards outlining the content buckets available for our users. Each content bucket card has a description explaining what they will learn in each section, helping users decide their own user journeys.
AsyncAPI Docs now has the mermaidJS dependency, allowing us to create UML engineering diagrams with markdown syntax.
The Concepts content bucket now has a dedicated /Overview page with detailed instructions on contributing to this section.
We now have most of the spec terms defined under the Concepts content bucket, and we're so close to merging the remaining new pages for protocol via asyncapi/website#1013 and application via asyncapi/website#992.
The Tutorials content bucket now has a dedicated /Overview page with detailed instructions on contributing to this section.
We have 4 open pull requests for 4 new tutorials: create AsyncAPI document via asyncapi/website#1023, validate AsyncAPI document with Studio via asyncapi/website#1022, generate code via asyncapi/website#1025, and validate messages via asyncapi/website#1061.
When those pull requests are merged, we will have 4 new tutorials in the following order:
The Tools content bucket now has a dedicated /Overview page with detailed instructions on contributing to this section. (update for Generetor Tool docs is further below under point 7)
We also have an open pull request for adding CLI docs via asyncapi/website#1097.
The Guides content bucket now has a dedicated /Overview page with detailed instructions on contributing to this section.
We have 2 open pull requests for 2 new guides: asyncapi/website#1005 and asyncapi/website#1002.
The Generator Docs have been rewritten and merged into the /Generator repo. (Within a month or so, Florence will finish automating copying them over to the /website repo where the actual Docs lie via asyncapi/generator#872.) But the work of re-writing and incorporating UML engineering diagrams was successfully completed!
source: The above diagram depicts the entire process of passing the Template and AsyncAPI Document to the AsyncAPI generator tool, how the generator uses these inputs to generate the desired output, and example outputs you can get from the render engine.
AsyncAPI Docs will now have NEW componentfragments for content that is often re-used in Docs. (Ex: Installation Guide blocks are required in individual Tutorials, Tool documentation, and individual Guides.) This inspired us to create a re-usable CLI installation guide fragment via asyncapi/website#1113. The best part is the great UI because we're using the native collapsible feature from HTML tags <description> and <summary>.
As a result of all the fun our GSoD 2022 interns had, most of them have confirmed interest in continuing to be OSS Docs contributors to the project. Karuna, Florence, and Thulie have already expressed interest in becoming core maintainers! This means we grew our Docs contributors from 2 to 5, which meets our earlier envisioned goal of growing our Docs contributors to 2-3 more people.
We now have 4 proposed AsyncAPI Docs & Education projects for 2023. Thanks to starting a community vote asap, we can easily identify ahead of time which projects to propose later for Google Season of Docs 2023.
AsyncAPI Docs Analytics shows thousands of views for our /Concept pages! In fact, we can see that they've had over 15,620 views in the past 90 days.
AsyncAPI Docs Analytics also shows us that users have viewed the new Docs homepage 8,000+ times in the last 90 days.
We look forward to finalizing publishing our new tutorials and guides, so that once they're merged we have analytics for that new GSoD 2022 content too! Moving forward, we will add more new event tags to more elements (i.e. buttons, cards, etc.) throughout the Docs to better track our user's actions.
Even though we're a few weeks behind on merging our 4 new tutorials and 2 new guides pull requests (PRs), we're thrilled that we accomplished so much while mentoring junior OSS technical writers! We were able to add the /Guides content bucket and start 2 new PRs for that section, which was originally only a stretch goal. We also added enhancements such as installation fragment components and UML diagrams, which truly improve the visual learning experience. We even realized that the 4 new tutorial PRs had content that was perfect for being re-used into 4 new interactive tutorials that we will eventually add to the AsyncAPI Killercoda profile as a new 100-level learning path. Lastly, we successfully rewrote all the Generator Docs, which was a HUGE undertaking! (Florence wrote 70% of the Generator Docs and went the second mile by offering to code the automation needed for copying those docs from the /generator repo to the Docs /website repo.)
Of the 6 participants, only 3-4 had the ability to be the most present and contribute consistently. This means that the project progressed a little slower at times than expected, and resulted in us falling about 2-3 weeks behind on completing all GSoD tasks. (Luckily for us, all of our GSoD interns this year have volunteered to continue working on the remaining GSoD PRs until they're successfully completed and merged!) Thus, while we technically won't have the full result of our work ready by November 30th as originally planned, we will still finish all of our outlined goals from our original proposal to Google.
YES! We successfully gave AsyncAPI Docs an Information Architecture makeover, incorporated a few stretch goals, and grew our OSS Docs contributors to 3 more!
We learned that mentoring junior OSS Docs contributors can involve a longer learning curve than expected, with frequent check-ins and interactive tasks to help them "learn while doing". On a personal note, I (@alequetzalli) learned that developing a transparent and timely communication style with your writing team is vital so everyone feels safe giving and receiving feedback. Our OSS participants have joked in unison that Technical Writing is much more work than imagined!
In the future, if we participate in GSoD 2023, we would definitely do a few things differently. I would limit the interviews to no more than 50 interviews total, allowing more interview time with a live practice exercise with each candidate. During the interview, I would also make a point to identify how many hours per week each candidate will specifically commit to working so that we can have more consistent participant contributions. When the actual work begins, I would provide an extra editing workshop session because I noticed new OSS Docs writers do not usually know how to best review their own work.
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 extra mentoring. You will be surprised how quickly passion can supersede knowledge level.
- Join AsyncAPI Community
- AsyncAPI would like to hear from the community their vote on top 3 Docs & Education projects to select for 2023. Don't forget to vote 🗳 !
- Contributing to AsyncAPI
A BIG thank you 🤗 to all of our OSS contributors; without you, there would be no OSS initiative! 😄🎉
There is always something to do for OSS Docs, and it's no different for us! 😄
If you'd like to get involved, pick up an issue from our AsyncAPI GH Board.
That's it for now! -A.Q. 👩🏻💻 y Canela 🐕🦺