A list of Community Documentation that we need

[AceTheCreator]

Since we've established the community docs content bucket, here are some community documentations that are essential.

• Recognizing contributions [Maintainers, Contributors]
• Configuring release pipeline for NodeJS
• Configuring release pipeline for non-NodeJS
• How We tweet out all RCs and Major/Minor releases
• Getting started as a first-time contributor
• How to Open a Pull Request
• How to File an Issue
• Triaging GitHub Issues
• How can I post on official LinkedIn account
• How can I tweet from the official account
• How to create a new repository
• How to donate a project
• How do we care about old issues
• How CI works (what can be added and what not)
• How can I introduce changes in GH workflows
• How to become a TSC member
• How to become a code owner
• /rtm/ /dnm/ and /help
• dependabot
• autobumps
• slack rules
• toast in slack
• How to make blog contributions

Please feel free to suggest or remove topics from the list above :)

cc @alequetzalli @derberg @fmvilas @smoya @jonaslagoni @thulieblack @Barbanio

[AnimeshKumar923]

Hey @AceTheCreator, I see interesting topics for docs. 👀 Let me know how can I help. 😄

[thulieblack]

So here are the topics I'm proposing for us to get started with:

Onboarding Docs

• Getting started as a first-time contributor/ How to become an AsyncAPI contributor
• Onboarding for Code (i.e., how source code is set up and structured for each repo example)
• How to submit an Issue
• How to open a Pull Request
• How to Becoming a Triager and a Committer
• How to Become a Mentor (in cases like GSoC)
• How and what it means to be a TSC member (we have a YouTube onboarding video)

Expand our Style Guide Docs

• Continue the work for our AsyncAPI Style Guide

cc @alequetzalli @AceTheCreator @Barbanio

Please do add your suggestions

[quetzalliwrites]

Question, what do you mean by "onboarding for code?" Each repo in our project has setup instructions and info on what features are being built out.

[thulieblack]

Yes, yes, you are right. The readme has all the instructions to set the environment.

[fmvilas]

I still think it's important. Instructions on how to setup the environment or info on what features are being built out are not enough to onboard to a repo's code. To contribute, you often have to understand how the code is structured. It would be great to have this info instead of having to figure it out yourself.

[thulieblack]

Hey Fran, could you please share an outline of what the doc should consist

[fmvilas]

mmm I'm not sure about the outline. It would be different per project. But I can give you an example:

├─ dist
├─ src
│  ├─ models
│  ├─ controllers
│  ├─ views
├─ package.json

File/Directory	Description
dist	It's where the compiled code is located. Never modify it by hand or you'll lose your changes. Use src instead.
src	It's where the source code is located
src/models	Data models are located here
src/controllers	This is the code that handles the requests. It makes use of the models and renders a view.
src/views	The frontend. This is where you should go if you want to change the UI.

---

This is just a brief example. It's explaining the source code of an imaginary repository. Just so people know where to go to contribute.

Hope that helps!

[thulieblack]

Yes it does thank you

[quetzalliwrites]

Just dropping into say I love this proposed list! We def need all those items.

[thulieblack]

Thanks @alequetzalli.

Next step is to create awereness

[aayushk9]

We can add following docs in tutorials/getting-started section.

• Getting started as a first time contributor.
• How to Open a Pull Request.
• How to file an Issue.

In the docs/community section, we can consider including this three docs: How to Become a TSC Member, How to Become a Code Owner and How to Donate a Project.

[aayushk9]

I can work on this.

[quetzalliwrites]

We can add following docs in tutorials/getting-started section.

• Getting started as a first time contributor.
• How to Open a Pull Request.
• How to file an Issue.

Hey there, @aayushk9 ... not quite! 😺 NONE of those docs go under tutorials. Please pay special attention to the description that clearly states we are discussing docs/community only.

ALL community docs proposed and accepted will go under docs/community, and these must be organized into appropriate sub-directories too.

[aayushk9]

@alequetzalli Understood. We can consider adding a how-to sub-directory under docs/community, similar to the existing docs/tutorials/getting-started section and include topics such as

• How to submit an Issue.
• How to open a Pull Request.
• How to Becoming a Triager and a Committer.
• How and what it means to be a TSC member.
• How to make blog contributions.
• How do we care about old issues.

This will help new contributors guide themselves easily.

[quetzalliwrites]

Actually, I will finalize the information architecture (after discussing/getting feedback with docs triagers and @thulieblack ) and then share the final guidelines with the community because that is a little more advanced. 😃 Believe it or not, generic directories are not the best approach. That is why advanced tasks that affect docs are assigned to more advanved docs contributors.

note: a /how-to directory is generic and does not communicate individual areas clearly, you want to think about navigation directories with a clear name that communicates what you will find within that area.

[aayushk9]

@alequetzalli Thanks for clarifying the approach and providing insights into the documentation organization.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[thulieblack]

Some of the docs will be written under the 2024 Maintainership Program. I'll close this issue now