search

asyncapi / community

AsyncAPI community-related stuff.
https://www.asyncapi.com/community
90 stars 97 forks source link

A list of Community Documentation that we need #919

Open AceTheCreator opened 8 months ago

AceTheCreator commented 8 months ago

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

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

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

AnimeshKumar923 commented 8 months ago

Hey @AceTheCreator, I see interesting topics for docs. :eyes: Let me know how can I help. :smile:

thulieblack commented 5 months ago

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

Onboarding Docs

Expand our Style Guide Docs

cc @alequetzalli @AceTheCreator @Barbanio

Please do add your suggestions

quetzalliwrites commented 5 months ago

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 commented 5 months ago

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

fmvilas commented 5 months ago

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 commented 5 months ago

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

fmvilas commented 5 months ago

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 commented 5 months ago

Yes it does thank you

quetzalliwrites commented 4 months ago

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

thulieblack commented 4 months ago

Thanks @alequetzalli.

Next step is to create awereness

aayushk9 commented 4 months ago

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

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 commented 4 months ago

I can work on this.

quetzalliwrites commented 4 months ago

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 commented 4 months ago

@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

This will help new contributors guide themselves easily.

quetzalliwrites commented 4 months ago

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 commented 4 months ago

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

github-actions[bot] commented 4 days ago

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

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 :heart: