Community Documentation

[AceTheCreator]

Had a discussion with Alejandra about the community docs section, and I decided to make it a public discussion. after some interesting discussion, we came to the realization that reusing the layout of the doc in the community layout isn’t really nice and it also contradicts the main docs page.

So we were left with two approaches.

• Create a content bucket for the community docs in the /docs section

• Create an entirely different UI for community docs

[AceTheCreator]

cc @derberg @alequetzalli @fmvilas @mcturco

[magicmatatjahu]

Creating an additional bucket in the /docs would be very easier - in the second case we would have to change the script that changes mdx/md files to files that Nextjs treats as pages to be rendered. This is not difficult, but the first is much easier. I started doing it with Alejandra a long time ago, but I don't have time to do it for now, so if someone wants to do it, can take it over from me - or go with 1 option. Here is a PRs:

• feat: adding GSoD and GSoC pages website#642
• chore: split website data build process to several steps website#830

First PR adds UI part, second changes the building script.

[quetzalliwrites]

Well, you already know my vote 🗳 😂

I think the user journey would be more effective if they're added as a new content bucket: asyncapi.com/docs/community.

[AceTheCreator]

@derberg @fmvilas your thoughts are needed here

[fmvilas]

Yeah, agree with @alequetzalli it should be added as a new bucket.

[derberg]

yeah, I saw in few communities that community documentation is mixed with tooling documentation. Tbh though, it was only on simple docs pages, and I was always thinking the reason is they had no other option to do it because of the tooling they chose.

• Kubernetes is strange, they have community docs in main docs https://kubernetes.io/docs/home/ and community docs under separate domain https://www.kubernetes.dev/docs/ (I wonder if they match 😄 )
• Knative separates things
• Django separates things https://docs.djangoproject.com/en/dev/internals/contributing/
• React mixes things https://reactjs.org/docs/how-to-contribute.html
• Python separates things https://www.python.org/psf/get-involved/

I see pattern that mix comes when project is "small" in a way it covers a single tool. And when the project is big like AsyncAPI, so Python or Django, community docs are separated. I think it is simply because once you run project that is really community driven (React is not) then you provide much more community content than just contributor guide, or links to external resources.

We need to remember that in open source project there are 2 journeys, not only user journey but also contributor journey:

• majority of users stay as users
• some users will become contributors
• some contributors will not be users

This is why I think User should be separated from Community, but there should be a link between those, to address journey of user -> contributor.

asyncapi/docs is where AsyncAPI docs are
asyncapi/community/docs is where all the AsyncAPI Community docs are
asyncapi/docs/community is just a bucket with 2-4 short documents that "introduce" basics of the community, and send user for more to asyncapi/community/docs

If we put all community docs under asyncapi/docs/community then AsyncAPI community flow is:

• go to asyncapi/community to join our community and learn about all, how to contribute, community members, meetings, mentorships, etc
• but wait, you can learn there about meetings and mentorships, but docs, no, for docs like how to contribute go to asyncapi/docs/community

☝🏼 breaks the flow

[quetzalliwrites]

Ok, this idea was pitched in November of last year... but, so far all community votes are for it to be a new content bucket under our current docs...I'm not sure why no one else has voted in favor of this idea (usually diff ideas get at least a few votes), but if we go by community votes, then this idea hasn't gotten the approval needed to be implemented. Do you want to try to get a round of votes again? Not sure that's how we do things tho? I don't know if we should keep campaigning to try to get votes in what we want 🤔

If you don't want to try to get a round of votes again, then we need to go with the current community vote to place under: asyncapi.com/docs/community.

Yes, contributor docs are community docs, wherever those end up being placed. Just clarifying because I saw you mention spec user vs contributor docs, and it sounded like you thought we (the community) hadn't already covered/discussed/voted for that. :)

@derberg

[derberg]

Tbh I left my comment so long time ago that I no longer remember what was the reason.

I'm only afraid we make decision without checking full context. Like "should I wear jeans or sweatpants?" - the first answer is not jeans but where are you going exactly?

When new docs section was planned, there was a long discussion about the framework you proposed, the structure (Concepts etc). We also had already lots of docs. So the decision was based on a proposal with real examples.

With community docs I do not recall any focused discussion. What types of docs are these? what categories we have? how we group them? what will not be allowed? unless I'm missing something.

For example, for me #571 is community documentation and I always thought that content from that PR ends up along other community docs but as I understood during website PRs triage meeting, for you it is not community docs.

Now, quickly invented navigation of docs:

- Community (the newly proposed bucket)
  - Contributor
    - Simple contribution flow
    - Finding good first issues
    - Conventional commits
    - GitHub tricks and flows
    - Recommended tools
    - Becoming maintainer
    - Recommended git workflow
    - Path to becoming TSC member
  - Gratifications
    - Swags
    - **Mentorships** 
    - Bounty program for maintainers
  - Maintainer
    - GitHub Actions
    - Global and local workflows
    - Appointing maintainers
    - Being a mentor
    - Recognizing contributors
  - Governance and Transparency
    - How things work
    - TSC
    - Voting
    - Meetings organization
    - Communication channels
    - Project finanse
  - Community Health
    - Slack etiquette
    - Code of conduct
  - Support
    - Sponsorship
    - Ambassadors
    - Writing blog posts
  - Others
    - How to create new repository
    - How to donate project
    - How to make my tool visible to the community

And there can be a bunch more (I did not even cover detailed topics like style guide for docs). We have no more nesting possible there, so the structure is pretty flat.

If we really agree that all of this should be packed in already fully packed left nav, and that asyncapi/website#1299 will fix my concerns, then I rest my case.

[derberg]

@AceTheCreator I think it is all clear, we go with community docs under /docs and new community bucket.

Related PR asyncapi/website#1261

[quetzalliwrites]

🌟🌟🌟🌟🌟🌟🌟🤩🤩🤩👏🏾👏🏾