AsyncAPI Initiative: 2024 Google Season of Docs (GSoD) Application

[alequetzalli]

AsyncAPI Initiative: 2024 Google Season of Docs (GSoD) Application

Welcome to AsyncAPI's application for the 2024 Google Season of Docs (GSoD)!

In anticipation of our application for this year, we have created a new AsyncAPI Slack channel named #temp-gsod-2024 that anyone can join! First, join our Slack workspace and please respect our slack etiquette. Then join our temporary channel's #temp-gsod-2024 channel to coordinate 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-2024 slack channel for:

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

Below is the project proposal we're submitting to GSoD 2024. We then close with a reminder of how to get started as an AsyncAPI docs contributor. If AsyncAPI is accepted into GSoD 2024, we will conduct interviews and review portfolios. Stay tuned!

Read the 2023 GSoD case study summarizing the work involved and results.

---

Onboarding Contributor Guides & Expand Community Docs

About AsyncAPI

AsyncAPI (currently version 3.0.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 such as 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.

Proposed AsyncAPI Docs Projects

Current AsyncAPI Docs Problem

The AsyncAPI documentation lacks a persona-driven journey for diverse roles, such as documentation contributors, code contributors, ambassadors, maintainers, etc. Consequently, the AsyncAPI onboarding experience is not as efficient as it could be for new contributors, often resulting in onboarding calls being perceived as bottlenecks.

First Solution: Onboarding Contributor Guides

To address this issue, the AsyncAPI documentation needs to create a set of onboarding guides to automate onboarding sessions for new contributors.

• Onboarding Code Contributor Guide
• Onboarding Ambassador Guide
• Onboarding Maintainer Guide

Second Solution: Expand Community Docs

Automating the AsyncAPI onboarding experience also involves documenting important workflows and processes for community members involved.

Contributor

• Simple Contribution Flow
• Identifying Good First Issues
• Following Conventional Commits
• Utilizing GitHub Tricks and Workflows
• Recommended Tools
• Path to Becoming a Maintainer
• Recommended Git Workflow
• Becoming a Technical Steering Committee (TSC) Member

Maintainer

• Utilizing GitHub Actions
• Implementing Global and Local Workflows
• Appointing New Maintainers
• Mentoring New Maintainers
• Recognizing Contributors

Ambassadors

• Ambassador Contributions
• Guidelines for Becoming an Ambassador

Gratifications

• Distribution of Swags
• Participation in the Mentorship Program
• Involvement in the Bounty Program

Governance and Transparency

• Understanding the Technical Steering Committee (TSC)
• Participation in Voting Processes
• Organizing and Participating in Meetings
• Utilizing Communication Channels Effectively
• Managing Project Finances

Community Health

• Adhering to Slack Etiquette
• Understanding and Upholding the Code of Conduct

Projects' Scope

In response, AsyncAPI is proposing two projects for the Google Season of Docs 2024:

1. Onboarding Contributor Guides: Streamline the onboarding process for new contributors by creating comprehensive guides tailored to their roles, automating the onboarding sessions effectively.
2. Expand Community Documentation: Document essential workflows and processes for community members involved to enhance the AsyncAPI onboarding experience.

Measuring Success

To gauge user engagement, success will be measured through various metrics, including the number of views, sessions, and unique users. Additionally, continuous monitoring of user feedback will be vital for further improving our community documentation and onboarding guides.

For instance, here are the analytics of the documentation sections created during the 2023 Google Season of Docs, captured between December 1, 2023, and March 25, 2024:

• /docs/concepts/asyncapi-document: 2,653 sessions with 449 new users.
• docs/tutorials/getting-started/request-reply: 455 sessions with 109 new users.

Timeline

The project will take approximately 4-6 months to complete.

• 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 2024. 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 documentation projects. Should we be selected, AsyncAPI would like to request a US $5000 budget from Google for each project. The request would then total a $10,000 budget for both projects. That said, we would also like to request an additional $350 in our budget to provide cool swag for participants.

Budget item	Total Amount
Technical writer writes, reviews, edits Onboarding Contributor Guides.	$5000
Technical writer writes, reviews, and edits Expanding Community Docs.	$5000
Award swag to selected Technical Writers	$350
TOTAL	$10,350

---

Contribute to AsyncAPI docs today

To get started as a docs contributor, follow the steps in the AsyncAPI Technical Writer Onboarding Checklist.

[yunchipang]

hello @alequetzalli, thank you so much for this guide. however, it appears the slack invitation link might be broken, would you share a updated one? thank you!

[alequetzalli]

Thank you for pointing this out! I will look into this and identify the updated link.

[alequetzalli]

fixed! 😄