AsyncAPI Documentation Report - Q1 2023
During Q1 2023, AsyncAPI Docs had 26,875 sessions and 13,506 unique users.
Docs sessions by content bucket:
/docs
: 26,875 sessions overall with 13,506 unique users./docs/concepts
: 2,316 sessions with 1,308 unique users./docs/tutorials
: 7,719 sessions with 4,679 unique users./docs/tools
: 2,955 sessions with 239 unique users./docs/guides
: 360 sessions with 6,011 unique users./docs/reference
: 10,807 sessions with 6,011 unique users.
Google Season of Docs 2023 (GSoD)
AsyncAPI is one of 13 OSS organizations accepted into Google Season of Docs 2023! Selected technical writers will work on two projects: documenting the AsyncAPI document in detail and creating interactive learning paths.
GSoD 2023 budget at AsyncAPI:
- We received a total budget of $10,350.
- $5,000 for documenting the AsyncAPI document section details
- $5,000 for creating interactive learning paths
- $350 for participant swag+shipping costs
GSoD technical writer applications are open
Alejandra Quetzalli is currently accepting applications for technical writers who want to participate in GSoD 2023 at AsyncAPI. The deadline for applications is April 15. Interested participants must complete this AsyncAPI GSoD 2023 written application available in a public Google form. We have received 18 applications to date.
If selected, the next step in the process for candidates will be to receive a direct follow-up message (DM) on AsyncAPI Slack and an email from Alejandra to schedule a LIVE editing and writing exercise interview. Up to 6 technical writers will be selected no later than April 21st.
AsyncAPI Docs style guide
The AsyncAPI Docs Style Guide has been created as an epic issue in our docs repository, broken into individual tasks:
- About this guide
- Accessibility
- Code examples
- Content buckets explanation
- Docs contribution guidelines
- Inclusive language
- Voice & Tone
- Grammar
- Numbers
- Punctuation
- Formatting
- Internalization (i18n) & Localization
- Links
- SEO
- Styling
- Version control
- Glossary
We did not pitch the style guide project for Google Season of Docs 2023 because creating a style guide does not require any knowledge of event-driven architecture (EDA). A style guide can be a good first issue to assign to new contributors unfamiliar with EDAs. By assigning them such tasks, we can help them learn about the basics of AsyncAPI and gradually move on to more complex documentation projects.
Spec 3.0 Release
AsyncAPI community members, including Jonas Lagoni, have begun planning documentation updates for the upcoming Spec 3.0 release in June. We are looking for contributors to assist with the documentation efforts. A meeting point has also been established for documentation in our community spec meetings until the release is live and the docs are ready.
Here are the Spec 3.0 release changes requiring documentation:
- 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
andexternalDocs
toinfo
- Splitting out server URL into host and pathname
- More reusable objects in components
Contributor growth
We are pleased to report that new docs contributors are already working on the AsyncAPI Docs Style Guide, such as Bhaswati Roy. Bhaswati impressed us with her research strength and ability to break down new topics into managable tasks.
We are thrilled to have new contributors working with us to help ensure consistency and clarity across all documentation.
Conclusion
Overall, Q1 2023 saw many sessions and unique users visiting the new AsyncAPI Docs after their information architecture makeover from the GSoD 2022 program. For the second time, we were accepted into Google Season of Docs 2023 for two projects that will help improve the quality of our documentation and provide valuable opportunities for contributors to develop new skills. We have also begun planning documentation updates for the upcoming Spec 3.0 release and started work on our first style guide, which will ensure that our documentation remains consistent and relevant.
Creating our first AsyncAPI Docs style guide is a major milestone because it will help ensure consistency and clarity across all documentation moving forward. With three new contributors working on the Style Guide and 18 applications already submitted for GSoD 2023 technical writing positions, the future of our docs community keeps looking bright!
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; Dev 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:
- Familiarize yourself with our project's Contribution Guide and our Code of Conduct.
- Head over to our Docs GH Board here.
- 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.
- 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.โจ