2022 Season of Docs Case Study: AsyncAPI #539
Closed
quetzalliwrites
started this conversation in
Docs & Education
Replies: 2 comments 1 reply
-
|
Confirming I have submitted this Case Study to Google. |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
I love the work we put into making this project what it is today. And Thank You!! @alequetzalli for giving us Juniors an opportunity, taking the risk, having patience, and time to mentor us. You are the best mentor and friend we could have ever asked for 🤗🤗🤗 |
Beta Was this translation helpful? Give feedback.
1 reply
-
|
Thank you for such kind words, @thulieblack! You were an absolute delight to mentor, you're always taking the initiative! ❤️ |
Beta Was this translation helpful? Give feedback.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
✨ AsyncAPI Initiative: Update Docs Information Architecture
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
🤯 Problem Statement & Proposal Abstract
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
/Conceptsdocs 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/Toolscontent bucket for documenting the AsyncAPI tools ecosystem. We also wanted to expand our/Tutorialsand start planning Troubleshooting Guides under a/Guidescontent 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
📝 Project Description
💡 Creating the 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.
💸 Budget
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.
👩🏻💻 Participants
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.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.
⌛ Timeline
Here is a short overview of our timeline; as you can see, the originally proposed timeline needed minor adjustments.
first-time-ticketsto get each new TW contributor started.GSoD 2022. Each TW starts creating documentation for their individual issues assigned/selected.🙌🏽 Results
Let's outline the top 10 results that AsyncAPI Docs has to show for GSoD 2022.
1️⃣ NEW AsyncAPI Docs Homepage
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.
2️⃣ NEW UML engineering diagrams
AsyncAPI Docs now has the mermaidJS dependency, allowing us to create UML engineering diagrams with markdown syntax.
3️⃣
/ConceptsThe
Conceptscontent bucket now has a dedicated/Overviewpage with detailed instructions on contributing to this section.We now have most of the spec terms defined under the
Conceptscontent bucket, and we're so close to merging the remaining new pages for protocol via asyncapi/website#1013 and application via asyncapi/website#992.4️⃣
/TutorialsThe
Tutorialscontent bucket now has a dedicated/Overviewpage 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:
5️⃣
/ToolsThe
Toolscontent bucket now has a dedicated/Overviewpage 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.
6️⃣
/GuidesThe
Guidescontent bucket now has a dedicated/Overviewpage 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.
7️⃣
/Generator-Tool DocsThe Generator Docs have been rewritten and merged into the
/Generatorrepo. (Within a month or so, Florence will finish automating copying them over to the/websiterepo 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.
8️⃣ NEW component
fragmentsAsyncAPI Docs will now have NEW component
fragmentsfor content that is often re-used in Docs. (Ex:Installation Guideblocks are required in individual Tutorials, Tool documentation, and individual Guides.) This inspired us to create a re-usable CLI installation guidefragmentvia asyncapi/website#1113. The best part is the great UI because we're using the native collapsible feature from HTML tags<description>and<summary>.9️⃣ NEW AsyncAPI Docs contributors
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.
🔟 Defined proposed 2023 goals for AsyncAPI Docs
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.
📏 Metrics
AsyncAPI Docs Analytics shows thousands of views for our
/Conceptpages! 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.
🔎 Analysis
What went well?
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
/Guidescontent bucket and start 2 new PRs for that section, which was originally only a stretch goal. We also added enhancements such asinstallation fragmentcomponents 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/generatorrepo to the Docs/websiterepo.)What hurdles or setbacks did we face?
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.
Does AsyncAPI consider the project successful?
YES! We successfully gave AsyncAPI Docs an Information Architecture makeover, incorporated a few stretch goals, and grew our OSS Docs contributors to 3 more!
❤️ Summary
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.
👉🏽 Appendix
Beta Was this translation helpful? Give feedback.
All reactions