community icon indicating copy to clipboard operation
community copied to clipboard
verified publisher icon asyncapi

[📑 Docs] Epic: Expand Community Documentation

Open bandantonio opened this issue 1 year ago • 6 comments

What Dev Docs changes are you proposing?

Create Onboarding Contributor Guides & Expand Community Docs as a part of the AsyncAPI Mentor/Maintainership Program 2024

Why the need?

The AsyncAPI documentation lacks a persona-driven journey for diverse roles, such as documentation contributors, code contributors, ambassadors, maintainers, etc. Consequently, the AsyncAPI onboarding experience is not as efficient as it could be for new contributors, often resulting in onboarding calls being perceived as bottlenecks.

Program Scope

The scope includes, but not limited to creating the following documentation:

Contributor Onboarding

  1. Contribution Flow
    • Create a step-by-step guide for new contributors on what to do before submitting a PR.
    • Role-based guides
      • Code Contributor: #1725 (@SaxenaAnushka102)
      • ✅ Maintainer:
        • #1638 (@Aahil13)
        • #1767
      • ✅ Ambassador:
        • #1641 (@ezinneanne)
        • #1767
    • Recommended tools
      • PR: #1777 (@ezinneanne)
  2. Conventional Commits
    • Document commit message conventions to maintain a clear repository history.
    • PR: #1733 (@Aahil13)
  3. Identifying Good First Issues
    • Guide contributors on finding beginner-friendly issues and interpreting issue labels.
    • PR: #1815 (@SaxenaAnushka102)
  4. Git Workflow
    • Outline best practices for branching, rebasing, and handling PR reviews effectively.
    • PR: #1772 (@bandantonio)

Maintainer Guidelines

  1. Utilizing GitHub Actions (@Aahil13)
    • Document how to set up and optimize workflows using automation tools.
    • Reference: https://github.com/asyncapi/.github
  2. Recognizing Contributors & Appointing New Maintainers (@SaxenaAnushka102)
    • Define selection criteria, nomination process, and onboarding checklist for new maintainers.
    • ❗️Requires community input and research.
  3. Mentoring New Maintainers (@ezinneanne)
    • Develop strategies for knowledge transfer to support new maintainers.
    • ❗️Requires community input and research.

Community Health and Engagement

  1. Adhering to Slack Etiquette (@Aahil13)
    • Establish best practices for respectful and effective communication on Slack.
    • Base the document on existing etiquette and provide links to Slack guidelines.
  2. Upholding the Code of Conduct (@ezinneanne and @SaxenaAnushka102)
    • Ensure contributors understand the Code of Conduct.
    • Provide guidelines on reporting discrimination and conflict resolution processes.
    • Reference the existing CoC documentation.

Out of Scope

Governance and Transparency

  1. ✅ Understanding the TSC (Technical Steering Committee) (@bandantonio)
  2. Organizing Meetings
    • Provide guidelines for structuring, scheduling, and running effective meetings.
  3. Restream Onboarding
    • Document the onboarding process for using Restream for community events.

Documentation structure and organization

The scope of creating new and updating/refactoring the existing documentation triggered a parallel stream of work related to revising the documentation structure within the community repository:

  • #1650

This stream focuses on providing a streamlined experience for both newcomers and existing community members to explore documentation efficiently within the repository, and effectively follow them during their contribution journeys.

Measuring Success

To gauge user engagement, success will be measured through various metrics, including the number of views, sessions, and unique users. Additionally, continuous monitoring of user feedback will be vital for further improving our community documentation and onboarding guides.

Code of Conduct

  • [X] I agree to follow this project's Code of Conduct

bandantonio avatar Dec 18 '24 20:12 bandantonio

Hi, @bandantonio thanks. Let's start with the Onboarding Contributor Guides first and then we can work move to Expand AsyncAPI Community Docs. I think we can draw some inspiration from @quetzalliwrites proposal https://github.com/orgs/asyncapi/discussions/1136

For the Epic, maybe we can also adopt something we had for the AsyncAPI Style Guide: https://github.com/asyncapi/community/issues/1683. It'll be useful for our case as well.

cc @quetzalliwrites @wise4rmgod

thulieblack avatar Dec 19 '24 07:12 thulieblack

Hello @bandantonio!

I hope you're having a wonderful day.

For the first project, I created a PR for my first draft of the Onboarding Maintainers Guide. I look forward to your review: https://github.com/asyncapi/community/pull/1638

Cc: @quetzalliwrites

Aahil13 avatar Jan 10 '25 15:01 Aahil13

Hello @bandantonio

Happy new week!

For the first project, I have made a PR of my first draft on Onboarding Ambassadors Guide. I look forward to your review: asyncapi/website#1641

Cc: @quetzalliwrites

ezinneanne avatar Jan 13 '25 03:01 ezinneanne

Hello @bandantonio

I have made the requested changes.

ezinneanne avatar Jan 18 '25 03:01 ezinneanne

Hello @bandantonio @thulieblack Happy New Week! I have made a PR for my first draft on the Expand docs: contributor. I added the two files in the PR #1730. I look forward to your review.

ezinneanne avatar Feb 17 '25 14:02 ezinneanne

Contributor Onboarding

  1. Contribution Flow
  • Create a step-by-step guide for new contributors on what to do before submitting a PR.
  • Reference: https://github.com/asyncapi/website/blob/master/CONTRIBUTING.md
  1. Conventional Commits
  • Document commit message conventions to maintain a clear repository history.
  1. Identifying Good First Issues
  • Guide contributors on finding beginner-friendly issues and interpreting issue labels.
  1. Git Workflow
  • Outline best practices for branching, rebasing, and handling PR reviews effectively.

Maintainer Guidelines

  1. Utilizing GitHub Actions
  • Document how to set up and optimize workflows using automation tools.
  • Reference: https://github.com/asyncapi/.github
  1. Recognizing Contributors & Appointing New Maintainers
  • Define selection criteria, nomination process, and onboarding checklist for new maintainers.
  • Requires community input and research.
  1. Mentoring New Maintainers
  • Develop strategies for knowledge transfer to support new maintainers.
  • Requires community input and research.

Community Health and Engagement

  1. Adhering to Slack Etiquette
  • Establish best practices for respectful and effective communication on Slack.
  • Base the document on existing etiquette and provide links to Slack guidelines.
  1. Upholding the Code of Conduct
  • Ensure contributors understand the Code of Conduct.
  • Provide guidelines on reporting discrimination and conflict resolution processes.
  • Reference the existing CoC documentation.

Governance and Transparency - Anthon will mainly do this work under the Comunity repo reorg.

  1. Understanding the TSC (Technical Steering Committee)
  • Document the role and responsibilities of the TSC.
  1. Organizing Meetings
  • Provide guidelines for structuring, scheduling, and running effective meetings.
  1. Restream Onboarding
  • Document the onboarding process for using Restream for community events.

thulieblack avatar Mar 07 '25 08:03 thulieblack

Great work everyone: @Aahil13 @ezinneanne @SaxenaAnushka102 @thulieblack ! What a remarkable milestone! 🥳🎉

bandantonio avatar Jul 10 '25 11:07 bandantonio

We need to create separate issues for the out-of-scope. Aside from this, woow, we're done! Congratulations everyone!

thulieblack avatar Jul 10 '25 11:07 thulieblack

Thank you so much @bandantonio and @thulieblack This program was a rewarding experience for me, thank you for guidance and patience.

ezinneanne avatar Jul 10 '25 14:07 ezinneanne