AsyncAPI Docs Report - April 2023

In April 2023, the AsyncAPI documentation experienced significant growth with 8,889 sessions and 4,575 unique users, including 2,895 new users. April was a strong month for our expanding docs community.

Google Season of Docs 2023 (GSoD) at AsyncAPI

We are thrilled to introduce this year's selected technical writing candidates for the 2023 Google Season of Docs (GSoD) at AsyncAPI!

2023 GSoD Accepted Technical Writer Candidates

Alejandra Quetzalli has chosen four outstanding candidates to collaborate with us for GSoD this year: Mahfuza, Bhaswati, Rohit, and Hridyesh.

Overview of the LIVE Writing/Editing Interviews

During the LIVE interview session, 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. Some candidates faced challenges with staying focused on writing, while others struggled to generate ideas due to nerves or the live format of the exercise. A few candidates had difficulty spotting errors and completing the editing task.

However, Alejandra did not disqualify candidates who experienced nerves, writer's block, or had limited editing skills. Instead, she guided them with questions and suggestions, encouraging them to search for answers online during the call. The main objective was to evaluate the candidates' problem-solving skills, ability to accept feedback, and integrate suggestions for improvement. The following sections outline the writing and editing exercises and the selection criteria for the candidates.

The Writing Part

For the writing exercise, Alejandra utilized an old commit from the 2022 GSoD project, which contained numerous errors for candidates to identify and fix. Some examples of these errors include:

• Multiple preview deployment links instead of live links to actual documentation.
• Content more appropriate for the Background context section crammed into the Introduction.
• Inadequate tutorial steps that lacked sufficient technical background context for first-time users.

The Editing Part

For the editing exercise, Alejandra used the same old commit from the 2022 GSoD project for some candidates. For those who progressed further during the writing exercise, she provided a second block of content to edit that was unformatted and contained repeated mistakes. The purpose of this unformatted text was to assess the candidates' ability to:

• Research terms like CLI, Node.js, macOS, etc., instead of assuming they know the correct spelling.
• Use the replace all keyboard shortcut to fix repeated mistakes.
• Think to check and confirm the correct spelling of AsyncAPI during an AsyncAPI interview.

Candidate Selection Criteria

The following factors were considered when assessing candidates:

• A humble attitude that actively listens and incorporates feedback.
• Strong collaborative abilities.
• A clear writing style.
• Technical writing experience and passion.
• Editing experience and approach.
• Effective use of grammar tools (e.g., Grammarly) and tech writing research tools (e.g., Phind.com, ChatGPT).
• Competency in researching with search engines such as Google.

Spec 3.0 Release

AsyncAPI community members, including Jonas Lagoni and Sergio Moya, have started the process of identifying Spec 3.0 Subject Matter Experts (SMEs) who can provide the necessary background context for our technical writers to begin updating our documentation.

While Alejandra and Sergio are currently the only ones sharing the Spec 3.0 writing work, we're actively seeking more contributors to join their writing efforts.

The following Spec 3.0 release changes require documentation updates:

• Request/reply
• Operation/channel decoupling
• Operation action: pub/sub confusion
• Unified referencing behavior: using $ref instead of string
• Common metadata fields
• Moving root properties tags and externalDocs to info
• Splitting out server URL into host and pathname
• More reusable objects in components

Contributor Growth

We are delighted to report an increase in new docs contributors collaborating on the AsyncAPI Docs Style Guide, working alongside Bhaswati Roy. We would like to recognize and thank Abhishek for his ongoing contributions to our Style Guide and Mahfuza for proactively opening PRs to fix documentation bugs.

Our gratitude goes out to our new contributors for their valuable contributions to the expansion and improvement of our documentation!

Conclusion

April 2023 has been an exciting month for AsyncAPI, as we welcomed exceptional technical writing candidates through 2023 GSoD and expanded our community of docs contributors again. These developments will enhance the quality of AsyncAPI documentation and foster a more collaborative environment. We eagerly anticipate the progress our technical writers will make, addressing Spec 3.0 release changes with the support of Subject Matter Experts (SMEs) and new contributors. Our growing docs community, demonstrated by the work on the AsyncAPI Docs Style Guide and proactive bug fixing, showcases the dedication of our contributors. 2023 GSoD at AsyncAPI signifies a major milestone in our community's journey towards better documentation, a stronger docs community, and an improved overall experience for AsyncAPI users.

How to contribute to AsyncAPI Docs

Did you know that you can contribute Docs to AsyncAPI as well? Code isn't the only way to contribute to OSS; docs are a huge help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️

To get started as a Docs contributor:

1. Familiarize yourself with our project's Contribution Guide and our Code of Conduct.
2. Head over to our Docs GH Board here.
3. Pick an issue you would like to contribute to and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!

Tag me in your AsyncAPI Doc PRs

Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or GitHub Discussions via my GitHub handle, /alequetzalli 🐙.

Talk to me

I want and need to listen 👂🏽 to all of your perspectives and ideas. Please don't be shy to express to me what you think needs to be documented first or what is missing. 📝 There's a lot of good work ahead, but you determine our content roadmap because the OSS community needs should always come first.✨