Propose New Docs Projects for AsyncAPI's 2024 Google Season of Docs Application

[quetzalliwrites]

Propose New Docs Projects for AsyncAPI's 2024 Google Season of Docs Application

Since Google set to open applications for the 2024 Season of Docs (GSoD) on February 22nd, we're excited to start gathering project proposals for AsyncAPI's application. Helping us identify documentation gaps is a fantastic opportunity to impact our community substantially. ❤️

📢🐻 We invite you to propose 1-2 documentation projects that could be realistically completed during the 2024 GSoD timeline, assuming AsyncAPI is selected.

I'd like to remind you: Please ensure your proposals are original and reflect a genuine understanding of our documentation's current needs and future direction. Direct submissions created with ChatGPT or similar AI tools will not be considered. We're looking for your unique insights and ideas!

[fmvilas]

Not sure exactly how to frame my proposal here but I'm gonna try 😅

I love the current state of our docs. They're great! We teach general concepts and offer tutorials and guides that combine theory (specification) and practice (tools). We have effectively "linked" specification -> tools (in this direction). What I'm missing now is the opposite direction: tools -> specification. It's pretty common that while editing the AsyncAPI document and using the tools, you find blockers because you either made a mistake on the AsyncAPI document or the tool triggers a warning/error for another reason.

Most of our tools log errors in the console trying to explain what went wrong. The error messages are usually not good enough and the console is not the best place to explain complex concepts. It would be awesome if our tools offered a link to a documentation page where they explain potential reasons why you're seeing this error, potential ways to fix it, and also take the opportunity to explain parts of the spec, concepts, etc.

I think starting with the AsyncAPI CLI would be a good exercise for us. Related issue: asyncapi/cli#872.

It's a good opportunity to bring people to the documentation pages to solve specific problems they have right now.

[quetzalliwrites]

@fmvilas Here's how I understand your proposal and scope, please let me know if you agree...

2024 GSoD project proposal: Troubleshooting Guides for AsyncAPI CLI

• Objective: Create comprehensive troubleshooting guides that address common errors encountered while using the AsyncAPI Command Line Interface (CLI). The documentation should provide users with detailed explanations of underlying issues, guidance on avoiding common pitfalls, and specific solutions.
• Scope: The project scope should include: (1) identifying frequent errors and challenges users face with the AsyncAPI CLI, (2) writing troubleshooting guides, and (3) linking these guides directly from error messages within the CLI.
• Goal: Turn error encounters into learning opportunities, improving tool usability and specification familiarity.

[derberg]

This one is tricky and advanced. It is not only about writing good docs, but also identifying if some docs exist already and link them properly. Technically it is complex as well, @fmvilas correct me if I'm wrong but it is not only CLI related. Some errors come from CLI, some are populated by CLI from the dependencies it uses:

• bad and sometimes not clear errors from AJV that is used by AsyncAPI Parser and later in the CLI - is a CLI the right place to add the link to more docs? not parser so it is also useful for Studio and other tools that validate AsyncAPI documents with the parser?
• errors thrown during generation of app or models should rather be extended in Generator and Modelina

Solving it on CLI side will be a complex solution as dependencies that we use are not yet aligned with a common way of throwing errors.

So yeah - linking docs in errors - I would suggest it is a stretch objective, and requires discussion. It is not much docs related but rather developer experience

But yes, having troubleshooting guides like:

• Why am I getting all these damn Anonymous models when I generate code?
• How can I solve error Property "PLACEHOLDER" is not expected to be here
• I get This template is not compatible with the current version of the generator but how do I check what generator versions is my template compatible with?

Still, some docs I think will be long to different tools.

[quetzalliwrites]

Thanks for this write up! Appreciate all the information I can get on this new idea 💡 ...

Ah. I should have been clearer in my earlier comment. I meant to say that starting with the case of the CLI alone, it would be great to start documenting current/known terminal errors and issues in our CLI. I am willing to bet you already have examples in your mind, even more that the ones you wrote above 😸

[GUNGODD]

How about creating another repository where we can raise errors that are undefined or not defined within our documentation? This way, users can rely on the AsyncAPI maintainer to address these issues, and the maintainer can resolve them. Additionally, we can then add the content to our documentation.

The process will look like this:

Users encounter an error (undefined or not mentioned inside our documentation) while using the AsyncAPI.
They report the error by posting it in the console, along with additional information such as error messages and any other relevant details.
A link to the repository where the issue was created is provided within the console.
The issue is then posted in the repository, allowing maintainers to review the error/bug.
The maintainer reviews the reported error/bug and manually adds the solution to the documentation.

[Amzani]

I agree with @derberg, It's quite advanced and beyond docs.

I love the idea of creating a global AsyncAPI error/warning dictionary on the website where we document these errors while they are encountered. (e.g https://www.twilio.com/docs/api/errors#50000-59999)

User stories

• U1) As a tool contributor (CLI, Studio...), I want to add an error/warning in the dictionary without leaving my repo
• U2) As a documentation maintainer, I want to review new error/warning dictionary content
• U3) As a tool contributor (CLI, Studio...), I want to link the error/warning documentation with runtime errors/warning

[CBID2]

I think a good project to focus on would be fixing the onboarding docs for first-time contributors. As someone who has maintained other people’s open source projects, having a strong contribution pathway would make it easier for people to join.

[quetzalliwrites]

Thank you for your suggestion on enhancing onboarding docs for first-time contributors. We are certainly working on adding more onboarding guides! We also appreciate you joining the public discussion since many folks are shy about docs discussions! ⭐

While vital, GSoD focuses on more advanced documentation needs beyond initial onboarding guides. These projects can significantly benefit from dedicated, in-depth effort over the program's timeline, including deep technical guides or comprehensive tutorials for advanced features.

[CBID2]

Ohh ok. Back to the drawing board then lol 😂

[quetzalliwrites]

Yes! def propose another idea if you want! 🐻📢

[CBID2]

Just out of curiosity, how advanced do the project proposals have to be?

[derberg]

We should have one project that is "Help reaching goal from https://github.com/orgs/asyncapi/discussions/948 which is Expand the Community Documentation"

• Hire experienced writer that can work independently, knows docs-work and do not need mentoring. Best if person worked on community docs in the past.
• One person will not be able to handle all the docs but for sure could:
  • Define structure - I have stron opinion that in case of onboarding guides we should have a persona-driven structure - or maybe not a structure, but for sure a persona-driven journey document that would make it easier to pic the right docs for the right persona. In the past when I was thinking about this idea - I thought it is an innovation that nobody did yet, but recently I learned about https://layer5.io/community/newcomers that is a great starting point that explains the idea of the journey. I just think in our case the journey is a bit more complex, as we have a journey of docs contributor, code contributor, ambassador, maintainer, etc.
  • Focus on first set of onboarding guides that would be: Contributor Onboarding - this would be the best as we have a great SME (input provider) that did like 100s onboarding sessions with contributors - @AceTheCreator - So GSoC contractor would not be alone and have an expert to learn from

[Barbanio]

I love the proposal, @alequetzalli! I wonder if we could add publishing articles or blog posts in the Ambassador's Journey as a possible first engagement, as it's more accessible for some people than attending an event.

[CBID2]

I love the proposal, @alequetzalli! I wonder if we could add publishing articles or blog posts in the Ambassador's Journey as a possible first engagement, as it's more accessible for some people than attending an event.

I mentioned this. Here's her response: #1069 (reply in thread)

[Barbanio]

I mean only to the Ambassador Journey since writing articles and posts is contemplated as a contribution in the Ambassador Program.

[CBID2]

I mean only to the Ambassador Journey since writing articles and posts is contemplated as a contribution in the Ambassador Program.

Ohh thanks for clarifying

[quetzalliwrites]

I love the proposal, @alequetzalli! I wonder if we could add publishing articles or blog posts in the Ambassador's Journey as a possible first engagement, as it's more accessible for some people than attending an event.

Yes @Barbanio, good idea!

[CBID2]

@alequetzalli, will you add Asyncapi to Google Seasons of Docs’ repo: https://github.com/google/season-of-docs/blob/main/2024-participants/interested-organizations.md

[quetzalliwrites]

Yep, we will do that too. We can't add that until we have written our project application submission. As you know from this discussion, we are currently taking submissions. 😸

[quetzalliwrites]

What do we think about proposing the following projects for 2024 GSoD?

We could have a focus on onboarding guides for different roles within the AsyncAPi community + expand community docs with various topics we've been requested for a while now.

cc @fmvilas @derberg @thulieblack @Barbanio @smoya @TRohit20

Project 1: Onboarding Contributor Guides

• onboarding docs contributor guide (I'm currently writing this one, it's the Onboarding Guide for Technical Writers)
• onboarding code contributor guide
• onboarding ambassador guide
• onboarding maintainer guide

Project 2: Expand Community Docs

• how to become tsc member
• how to contribute to the spec
• etc.

[thulieblack]

100% happy with this. Thanks Ale 💜

[TRohit20]

From my POV, Both the projects look very solid and much needed, with the amount of people texting me on a daily basis + the growth in contributors and AsyncAPI as a project in itself demands for us to now have very detailed and helpful Onboarding and community docs. They would benefit both the community and contributors, I am strongly in support and aligned with the project ideas. thank you, Alejandra.

Oh, Btw, I would be super happy to write the proposal for GSoD with you, shadow you atleast to learn how you manage to write proposals so good ;) (only if it's okay with you)

[quetzalliwrites]

Yes, I think it would be ok to let you assist in our proposal; I do think you're trustworthy enough to do a responsible job. 😸 I can assign you a section of it for example... let's discuss further in DM. ✌🏽