Skip to content

Instantly share code, notes, and snippets.

@alequetzalli
Created December 2, 2022 00:12
Show Gist options
  • Save alequetzalli/1df44522de1b0c66f3471e70b2b84945 to your computer and use it in GitHub Desktop.
Save alequetzalli/1df44522de1b0c66f3471e70b2b84945 to your computer and use it in GitHub Desktop.

๐Ÿ“„ AsyncAPI Docs update (November 2022)

As an Open-Source (OSS) contributor, I volunteer to write periodic updates about the AsyncAPI Docs ecosystem.

๐Ÿฆ„ This is Ale's personal summary

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. ๐Ÿ˜€๐Ÿ‘๐Ÿฝ

๐Ÿ“ข 2022 Season of Docs Case Study: AsyncAPI

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.


โœจ 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 /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

๐Ÿ“ 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.

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

๐Ÿ‘ฉ๐Ÿปโ€๐Ÿ’ป 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.

  • ๐Ÿง•๐Ÿพ 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.

โŒ› Timeline

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-tickets to 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.

๐Ÿ™Œ๐Ÿฝ 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.

AsyncAPI Docs homepage with content buckets

2๏ธโƒฃ NEW UML engineering diagrams

AsyncAPI Docs now has the mermaidJS dependency, allowing us to create UML engineering diagrams with markdown syntax.

mermaidJS UML engineering diagrams

3๏ธโƒฃ /Concepts

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.

AsyncAPI concept pages

4๏ธโƒฃ /Tutorials

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:

new tutorials and order for AsyncAPI docs

5๏ธโƒฃ /Tools

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.

6๏ธโƒฃ /Guides

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.

7๏ธโƒฃ /Generator-Tool Docs

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!

mermaidJS diagram showing the Generator Tool process

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 componentfragments

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>.

cli installation fragment component

cli installation fragment component

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 /Concept pages! In fact, we can see that they've had over 15,620 views in the past 90 days.

AsyncAPI analytics for concepts docs

AsyncAPI Docs Analytics also shows us that users have viewed the new Docs homepage 8,000+ times in the last 90 days.

Screen Shot 2022-11-29 at 8 29 06 PM

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 /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.)

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


โค๏ธ Thanking our Contributors

A BIG thank you ๐Ÿค— to all of our OSS contributors; without you, there would be no OSS initiative! ๐Ÿ˜„๐ŸŽ‰

๐Ÿ™๐Ÿฝ Contributors Needed

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 ๐Ÿ•โ€๐Ÿฆบ

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment